openapi: {{ openapi_spec }} info: title: {{ api_name }}-api version: {{ api_version }} security: - BearerAuth: [] - EarthDataLogin: [] {% if security_environment == 'EDC' %} # See https://github.com/ASFHyP3/hyp3/pull/2009 for context. servers: - url: / - url: /api {% endif %} paths: /costs: get: description: Get table of job costs. responses: "200": description: 200 response content: application/json: schema: $ref: "#/components/schemas/costs_response" /jobs: post: description: Submits a list of jobs for processing. requestBody: content: application/json: schema: $ref: "#/components/schemas/post_jobs_body" required: true responses: "200": description: 200 response content: application/json: schema: $ref: "#/components/schemas/jobs_response" patch: description: |- Update a list of up to 100 jobs. The update is not transactional, so it's possible that only some of the jobs will be updated if an error occurs. requestBody: content: application/json: schema: $ref: "#/components/schemas/patch_jobs_body" required: true responses: "200": description: 200 response content: application/json: schema: type: object get: description: Get list of previously run jobs. parameters: - name: user_id in: query schema: $ref: "#/components/schemas/user_id" - name: status_code in: query schema: $ref: "#/components/schemas/status_code" - name: start in: query schema: $ref: "#/components/schemas/datetime" - name: end in: query schema: $ref: "#/components/schemas/datetime" - name: name in: query schema: $ref: "#/components/schemas/name" - name: job_type in: query schema: $ref: "./job_parameters.yml#/components/schemas/job_type" - name: start_token in: query schema: $ref: "#/components/schemas/start_token" responses: "200": description: 200 response content: application/json: schema: $ref: "#/components/schemas/jobs_response" /jobs/{job_id}: patch: description: Update a job. parameters: - name: job_id in: path schema: $ref: "#/components/schemas/job_id" required: true requestBody: content: application/json: schema: $ref: "#/components/schemas/patch_job_body" required: true responses: "200": description: 200 response content: application/json: schema: $ref: "#/components/schemas/job" get: description: Get a previously run job. parameters: - name: job_id in: path schema: $ref: "#/components/schemas/job_id" required: true responses: "200": description: 200 response content: application/json: schema: $ref: "#/components/schemas/job" /user: patch: description: Submit or update an application for processing approval. requestBody: content: application/json: schema: $ref: "#/components/schemas/patch_user_body" required: true responses: "200": description: 200 response content: application/json: schema: $ref: "#/components/schemas/user" get: description: Get information about the logged in user. responses: "200": description: 200 response content: application/json: schema: $ref: "#/components/schemas/user" /bucket-policy/{bucket_name}: get: description: Get a bucket policy for `bucket_name` which allows HyP3 to write to that bucket. parameters: - name: bucket_name in: path schema: $ref: "#/components/schemas/bucket" required: true responses: "200": description: 200 response content: application/json: schema: $ref: "#/components/schemas/bucket_policy" components: schemas: costs_response: type: object description: > Dictionary whose keys are the job types available in this deployment. Each value is a fixed or variable cost definition. A fixed cost definition has a single cost key whose value is the credit cost of the job type. A variable cost definition has a cost_parameters key whose value is a list of job parameters, and a cost_table key whose value is a dictionary that allows looking up credit cost based on the job parameters listed in cost_parameters. The example response structure shows JOB_TYPE_A with a fixed cost definition, JOB_TYPE_B with a variable cost definition with one cost parameter, and JOB_TYPE_C with a variable cost definition with two cost parameters. For example, a JOB_TYPE_C job with job parameters {"foo": "foo_value1", "bar": "bar_value2"} would have a credit cost of 5. example: JOB_TYPE_A: cost: 1.0 JOB_TYPE_B: cost_parameters: [foo] cost_table: foo_value1: 1.0 foo_value2: 5.0 JOB_TYPE_C: cost_parameters: [foo, bar] cost_table: foo_value1: bar_value1: 1.0 bar_value2: 5.0 foo_value2: bar_value1: 2.0 bar_value2: 10.0 post_jobs_body: description: List for new jobs to submit for processing. type: object required: - jobs additionalProperties: false properties: validate_only: $ref: "#/components/schemas/validate_only" jobs: $ref: "#/components/schemas/list_of_new_jobs" patch_jobs_body: description: List of jobs to update with a new name. type: object required: - job_ids - name additionalProperties: false properties: job_ids: $ref: "#/components/schemas/job_ids_list" name: $ref: "#/components/schemas/name_patch" jobs_response: description: List of submitted jobs. type: object required: - jobs additionalProperties: false properties: validate_only: $ref: "#/components/schemas/validate_only" jobs: $ref: "#/components/schemas/list_of_jobs" next: $ref: "#/components/schemas/next_url" patch_user_body: description: Application for processing approval. type: object required: - use_case additionalProperties: false properties: use_case: $ref: "#/components/schemas/use_case" access_code: $ref: "#/components/schemas/access_code" user: description: Information about a user type: object required: - application_status - job_names - remaining_credits - user_id additionalProperties: false properties: application_status: $ref: "#/components/schemas/application_status" credits_per_month: $ref: "#/components/schemas/credits" job_names: $ref: "#/components/schemas/job_names_list" remaining_credits: $ref: "#/components/schemas/credits" use_case: $ref: "#/components/schemas/use_case" user_id: $ref: "#/components/schemas/user_id" application_status: description: Status of an application for processing approval. type: string enum: - NOT_STARTED - PENDING - APPROVED - REJECTED example: PENDING credits: description: Processing credits for running jobs. type: number minimum: 0 job_ids_list: type: array items: $ref: "#/components/schemas/job_id" job_names_list: type: array items: $ref: "#/components/schemas/name" list_of_new_jobs: description: Contains a list of new job objects. type: array minItems: 1 maxItems: 200 items: $ref: "./job_parameters.yml#/components/schemas/new_job" list_of_jobs: type: array items: $ref: "#/components/schemas/job" patch_job_body: description: Job fields to update. type: object minProperties: 1 additionalProperties: false properties: name: $ref: "#/components/schemas/name_patch" job: description: Contains information about a submitted job. type: object required: - job_id - user_id - job_type - job_parameters - request_time - status_code additionalProperties: false properties: job_id: $ref: "#/components/schemas/job_id" user_id: $ref: "#/components/schemas/user_id" job_type: $ref: "./job_parameters.yml#/components/schemas/job_type" job_parameters: $ref: "./job_parameters.yml#/components/schemas/job_parameters" request_time: $ref: "#/components/schemas/datetime" status_code: $ref: "#/components/schemas/status_code" execution_started: $ref: "#/components/schemas/execution_started" name: $ref: "#/components/schemas/name" bucket: $ref: "#/components/schemas/bucket" bucket_prefix: $ref: "#/components/schemas/bucket_prefix" files: $ref: "#/components/schemas/list_of_files" browse_images: $ref: "#/components/schemas/list_of_urls" thumbnail_images: $ref: "#/components/schemas/list_of_urls" logs: $ref: "#/components/schemas/list_of_urls" expiration_time: $ref: "#/components/schemas/expiration_time" processing_times: $ref: "#/components/schemas/processing_times" priority: $ref: "#/components/schemas/priority" credit_cost: $ref: "#/components/schemas/credits" validate_only: type: boolean default: false job_id: description: Unique identifier for a job type: string format: uuid example: 27836b79-e5b2-4d8f-932f-659724ea02c3 use_case: description: Reason for wanting to use HyP3. type: string example: I want to process data. access_code: description: Grants automatic user approval while the code remains active. type: string example: 123 user_id: description: Username from Earthdata Login. type: string example: myUserId datetime: description: Date and time object formatted according to ISO 8601 type: string format: date-time example: "2020-06-04T18:00:03+00:00" expiration_time: description: Date and time object formatted according to ISO 8601, representing the job's expiration time type: string nullable: true format: date-time example: "2020-06-04T18:00:03+00:00" status_code: description: Status of a submitted job. type: string enum: - PENDING - RUNNING - SUCCEEDED - FAILED example: SUCCEEDED execution_started: description: Whether a workflow execution has been started for the submitted job. type: boolean name: description: User provided text to name the job type: string minLength: 1 maxLength: 100 example: Job Name name_patch: description: User provided text to name the job, or null to delete the name type: string nullable: true minLength: 1 maxLength: 100 example: Job Name bucket: description: User provided text to define the product bucket, null for default type: string nullable: true minLength: 3 maxLength: 63 example: "my-example-bucket" pattern: "(?!(^((2(5[0-5]|[0-4][0-9])|[01]?[0-9]{1,2}).){3}(2(5[0-5]|[0-4][0-9])|[01]?[0-9]{1,2})$|^xn--|.+-s3alias$))^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$" bucket_prefix: description: User provided text to define the bucket prefix to place the product in type: string nullable: true minLength: 1 maxLength: 700 example: "{job_id}" pattern: "^(?!\/)(?!.*\/\/)(?:[A-Za-z0-9._\/-]|{job_id}|{name}){1,700}$" bucket_policy: description: An AWS S3 Bucket Policy that, when applied, will allow HyP3 to write to the bucket. type: object required: - Version - Statement additionalProperties: false properties: Version: type: string format: date example: "2012-10-17" Statement: type: array items: type: object example: >- [ { "Sid": "HyP3 bucket-level publish permissions", "Effect": "Allow", "Principal": { "AWS": "123456789012" }, "Action": [ "s3:ListBucket", "s3:getBucketLocation" ], "Resource": "arn:aws:s3:::my-example-bucket" }, { "Sid": "HyP3 object-level publish permissions", "Effect": "Allow", "Principal": { "AWS": "123456789012" }, "Action": [ "s3:GetObject", "s3:GetObjectTagging", "s3:PutObject", "s3:PutObjectTagging" ], "Resource": "arn:aws:s3:::my-example-bucket/*" } ] start_token: description: Token used for fetching subsequent results for large queries type: string next_url: description: Url provided for large search results that have been truncated. Use to fetch subsequent results. type: string list_of_files: description: List of downloadable files generated by the job. type: array items: type: object required: - filename - size - url additionalProperties: False properties: filename: type: string size: type: integer minimum: 0 url: type: string s3: $ref: "#/components/schemas/s3_object" s3_object: type: object additionalProperties: false required: - bucket - key properties: bucket: type: string key: type: string list_of_urls: type: array items: type: string priority: type: integer minimum: 0 maximum: 9999 processing_times: description: > List of run times for the job's processing steps in the order that they were executed. This field is null for failed jobs and non-null for successful jobs. type: array nullable: true items: oneOf: - type: array items: $ref: '#/components/schemas/processing_time_in_seconds' example: [200, 100, 150] - $ref: '#/components/schemas/processing_time_in_seconds' processing_time_in_seconds: description: > Run time in seconds for a processing step's final attempt. type: number minimum: 0 example: 50 securitySchemes: BearerAuth: description: |- Authentication via Earthdata Login Bearer Tokens; https://urs.earthdata.nasa.gov/documentation/for_users/user_token type: http scheme: bearer bearerFormat: JWT EarthDataLogin: description: |- Authentication requires the user to have an account at urs.earthdata.nasa.gov and log in at auth.asf.alaska.edu type: apiKey in: cookie name: asf-urs