openEO Orders API

openapi: 3.2.0
info:
  title: Openeo Orders API
  version: 0.1.0
  contact:
    name: openEO Consortium
    url: https://openeo.org
    email: openeo.psc@uni-muenster.de
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: 'Operations tagged Orders across 2 of this provider''s published API definitions: openeo-commercial-data-openapi.yaml, openeo-commercial-data-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://openeo.example/api/{version}
  description: The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a *recommendation* only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
  variables:
    version:
      default: v1
      description: API versioning is RECOMMENDED. As the openEO API is following [SemVer](https://semver.org/) only the MAJOR part of the stable version numbers (i.e. versions >= 1.0.0) SHOULD be used for API versioning in the URL. The reason is that backward-incompatible changes are usually introduced by major changes. Therefore, the version number in the URL MUST not be used by the clients to detect the version number of the API. Use the version number returned from `GET /` instead.
tags:
- name: Orders
  description: Management of commercial data orders
paths:
  /orders:
    get:
      summary: List all commercial data orders
      operationId: list-orders
      description: 'Lists all created orders submitted by a user, regardless of the status

        or the collection.


        It is **strongly RECOMMENDED** to keep the response size small by

        omitting all optional non-scalar values from objects in `orders` (e.g. `parameters`).

        To get the full metadata for an order clients MUST request `GET /orders/{order_id}`.'
      tags:
      - Orders
      security:
      - Bearer: []
      parameters:
      - $ref: ../../openapi.yaml#/components/parameters/pagination_limit
      responses:
        '200':
          description: List of orders and related links.
          content:
            application/json:
              schema:
                title: Orders
                type: object
                required:
                - orders
                - links
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/order'
                  links:
                    $ref: ../../openapi.yaml#/components/schemas/links_pagination
        4XX:
          $ref: ../../openapi.yaml#/components/responses/client_error_auth
        5XX:
          $ref: ../../openapi.yaml#/components/responses/server_error
    post:
      summary: Create a new order
      operationId: create-order
      description: 'Create an order for selected items (products).


        When an order is created through through this endpoint, the data isn''t yet ordered from the commercial data provider. The client MUST explicitly confirm the order through `POST /orders/{order_id}` whereupon the order is executed.


        The order can contain additional parameters that specify how the items should be delivered.

        For example, it might be possible to set the projection, resampling method, bit depth etc. of the delivered data.


        Back-ends SHOULD expose the available ordering parameters in `GET /collections/{collection_id}` in the `order_parameters` field, following the `process_parameters` schema of `GET /service_types`.


        Returns `Location` and `OpenEO-Identifier` header with the link to the detailed information about the order.'
      tags:
      - Orders
      security:
      - Bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - source_collection_id
              - items
              - parameters
              properties:
                source_collection_id:
                  type: string
                  description: Unique identifier of the collection.
                items:
                  type: array
                  description: Array of items IDs to order.
                  items:
                    $ref: '#/components/schemas/order_id'
                parameters:
                  $ref: '#/components/schemas/order_parameters'
      responses:
        '201':
          description: The order has been created successfully.
          headers:
            Location:
              required: true
              schema:
                description: 'Absolute URL to the newly created order.


                  The URL points to the metadata endpoint

                  `GET /orders/{order_id}` with the `{order_id}` being the

                  unique identifier (ID) of the created order.'
                format: uri
                type: string
                example: https://openeo.example/api/v1/orders/40264b5-c3ae-46f4-a907-0f612d763d97
            OpenEO-Identifier:
              required: true
              schema:
                $ref: '#/components/schemas/order_id'
        4XX:
          $ref: ../../openapi.yaml#/components/responses/client_error_auth
        5XX:
          $ref: ../../openapi.yaml#/components/responses/server_error
    servers:
    - url: https://openeo.example/api/{version}
      description: The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a *recommendation* only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
      variables:
        version:
          default: v1
          description: API versioning is RECOMMENDED. As the openEO API is following [SemVer](https://semver.org/) only the MAJOR part of the stable version numbers (i.e. versions >= 1.0.0) SHOULD be used for API versioning in the URL. The reason is that backward-incompatible changes are usually introduced by major changes. Therefore, the version number in the URL MUST not be used by the clients to detect the version number of the API. Use the version number returned from `GET /` instead.
  /orders/{order_id}:
    parameters:
    - $ref: '#/components/parameters/order_id'
    get:
      summary: Full metadata for an order
      operationId: describe-order
      description: 'Get full metadata of the order.


        Back-ends can optionally link to the spatial and temporal extent information and other metadata about the items using the relation type `item`, preferrably by implementing and linking to `GET /collections/{collection_id}/items/{item_id}`.'
      tags:
      - Orders
      security:
      - Bearer: []
      responses:
        '200':
          description: Full order information.
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/order'
        4XX:
          $ref: ../../openapi.yaml#/components/responses/client_error_auth
        5XX:
          $ref: ../../openapi.yaml#/components/responses/server_error
    post:
      summary: Confirm an order
      operationId: confirm-order
      description: 'Confirm the order, execute the purchase and ingest the data into a target collection.


        When an order is created through `POST /order`, the data isn''t yet ordered from the commercial data provider. The client MUST explicitly confirm the order whereupon the order is executed, the costs are deducted from the client''s account and the data is ingested in the target collection.


        The target collection is the collection through which the ordered data is made available. The source and the target collection can be the same or different, it''s up to the back-end if the ordered data id ingested into a new target collection or the existing source collection. Additionally, if the back-end creates new target collections, it can provide access to the union of all purchased products through the source collection.


        This endpoint only has an effect if `order:status` is `orderable`.


        If the user doesn''t have sufficient funds, the endpoint should return an error and `order:status` should not change.


        Otherwise, the `order:status` changes from `orderable` to `ordered` until a new order status (e.g. `succeeded` or `failed`) becomes available.'
      tags:
      - Orders
      security:
      - Bearer: []
      responses:
        '202':
          description: The order has been confirmed successfully.
        4XX:
          $ref: ../../openapi.yaml#/components/responses/client_error_auth
        5XX:
          $ref: ../../openapi.yaml#/components/responses/server_error
    delete:
      summary: Delete an order
      operationId: delete-order
      description: 'Removes the order and all ordered items from the back-ends.


        If an order is still in progress, it cancels the order.

        Costs MAY still occur.'
      tags:
      - Orders
      security:
      - Bearer: []
      responses:
        '204':
          description: The order and data has been successfully deleted.
        4XX:
          $ref: ../../openapi.yaml#/components/responses/client_error_auth
        5XX:
          $ref: ../../openapi.yaml#/components/responses/server_error
    servers:
    - url: https://openeo.example/api/{version}
      description: The URL of the API MAY freely be chosen by the back-end providers. The path, including API versioning, is a *recommendation* only. Nevertheless, all servers MUST support HTTPS as the authentication methods are not secure with HTTP only!
      variables:
        version:
          default: v1
          description: API versioning is RECOMMENDED. As the openEO API is following [SemVer](https://semver.org/) only the MAJOR part of the stable version numbers (i.e. versions >= 1.0.0) SHOULD be used for API versioning in the URL. The reason is that backward-incompatible changes are usually introduced by major changes. Therefore, the version number in the URL MUST not be used by the clients to detect the version number of the API. Use the version number returned from `GET /` instead.
components:
  parameters:
    order_id:
      name: order_id
      in: path
      description: 'Unique identifier of an order.

        This corresponds to the `id` property of an order.'
      required: true
      schema:
        $ref: '#/components/schemas/order_id'
  schemas:
    order:
      type: object
      title: Order
      description: 'Information about an order.

        The properties with the `order:` prefix follow the fields defined in the [STAC Order Extension](https://github.com/stac-extensions/order/tree/v1.0.0).'
      required:
      - id
      - order:status
      - order:date
      - source_collection_id
      - target_collection_id
      - costs
      properties:
        id:
          $ref: '#/components/schemas/order_id'
        order:id:
          type: string
          description: Identifier of the order at the data provider.
          example: 40264b5-c3ae-46f4-a907-0f612d763d97
        order:status:
          type: string
          description: 'The status of the order.

            * `orderable`: The item or asset is orderable via the provider scenario.

            * `ordered`: The item or asset is ordered and the provider is preparing to make it available.

            * `pending`: The item or asset is ordered but wait for an activation before being able for shipping.

            * `shipping` The item or asset order are being processed by the provider to provide you with the asset(s).

            * `succeeded`: The provider has delivered your order and asset(s) are available.

            * `failed`: The provider is not able to deliver the order.

            * `canceled` The order has been canceled.'
          enum:
          - orderable
          - ordered
          - pending
          - shipping
          - succeeded
          - failed
          - canceled
        order:date:
          type: string
          format: date-time
          description: The order time. Formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time.
          example: '2017-01-01T09:32:12Z'
        order:expiration_date:
          type: string
          format: date-time
          description: The validity time of the order. Formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time.
          example: '2999-01-01T00:00:00Z'
        source_collection_id:
          type: string
          description: Unique identifier of the source collection.
          pattern: ^[\w\-\.~\/]+$
          example: PLEIADES
        target_collection_id:
          type: string
          description: Unique identifier of the target collection. Can be the same as `source_collection_id`.
          pattern: ^[\w\-\.~\/]+$
          example: PLEIADES
        costs:
          $ref: ../../openapi.yaml#/components/schemas/money
        parameters:
          $ref: '#/components/schemas/order_parameters'
        items:
          type: array
          description: List of ordered item IDs.
          items:
            $ref: '#/components/schemas/item_id'
        links:
          type: array
          description: 'Links related to this order, e.g. to metadata for ordered items

            listed in `items`.


            It is highly RECOMMENDED to provide links with the

            following `rel` (relation) types:


            1. `item`: A link back to a valid STAC Item that has been ordered.

            Could be a link to `GET /collections/{collection_id}/items/{item_id}`.


            2. `order`: A link pointing to a dcoument describing the ordering

            terms and conditions of the data provider.


            For additional relation types see also the lists of

            [common relation types in openEO](#section/API-Principles/Web-Linking).'
          items:
            $ref: ../../openapi.yaml#/components/schemas/link
    item_id:
      type: string
      description: Unique identifier of the item. Must be unique within a collection.
      example: c8a1f88d-89cf-4933-9118-45e9c1a5df20
    order_parameters:
      type: object
      description: Key-value pairs of available `order_parameters` as listed at `GET /collections/{collection_id}` for filtering available items.
      additionalProperties:
        x-additionalPropertiesName: Order Parameter Name
        description: Value of the order parameter for the request.
      example:
        resamplingKernel: NN
    order_id:
      type: string
      description: Unique identifier of the order at the back-end, which MUST match the specified pattern.
      pattern: ^[\w\-\.~]+$
      example: fb6799ab
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: 'The Bearer Token MUST consist of the authentication method, a provider ID (if available) and the token itself. All separated by a forward slash `/`. Examples (replace `TOKEN` with the actual access token): (1) Basic authentication (no provider ID available): `basic//TOKEN` (2) OpenID Connect (provider ID is `ms`): `oidc/ms/TOKEN`. For OpenID Connect, the provider ID corresponds to the value specified for `id` for each provider in `GET /credentials/oidc`.'
    Basic:
      type: http
      scheme: basic
externalDocs:
  url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/commercial-data/README.md
x-refined-from:
- openeo-commercial-data-openapi.yaml
- openeo-commercial-data-openapi.yml