openapi: 3.0.2
info:
  title: openEO API - Commercial Data Extension
  version: 0.1.0
  description: >-
    The Commercial Data Extension to the openEO API provides an interface for discovering,
    ordering and using commercial data in openEO.
  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'
externalDocs:
  url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/commercial-data/README.md
tags:
  - name: Orders
    description: Management of commercial data orders
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.
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`](https://openeo.org/documentation/1.0/developers/api/reference.html#tag/Secondary-Services/operation/list-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'
  '/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'
components:
  schemas:
    order_id:
      type: string
      description: >-
        Unique identifier of the order at the back-end, which MUST match the specified pattern.
      pattern: '^[\w\-\.~]+$'
      example: fb6799ab
    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:
      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'
  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'
  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