openapi: 3.0.1
info:
  title: Platform API for Gate
  description: This API is provided by a platform for the gate
  version: 0.4.0

components:
  parameters:
    RequestIdHeader:
      in: header
      name: X-Request-ID
      description: Correlation identifier for the request as defined by the client (required for traceability)
      schema:
        type: string
        format: uuid
      required: true
  schemas:
    ProblemDetail:
      type: object
      xml:
        name: problem
        namespace: "urn:ietf:rfc:7807"
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type.
          format: uri
          example: about:blank
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          format: int32
          example: 500
        title:
          type: string
          description: A short, human-readable summary of the problem type.
          example: Internal Server Error
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
          format: uri
          example: /api

paths:

  /v0/ping:
    parameters:
      - $ref: "#/components/parameters/RequestIdHeader"
    get:
      operationId: getPing
      responses:
        200:
          description: Gate is successfully authorized

  /v0/consignments/{datasetId}:
    parameters:
      - $ref: "#/components/parameters/RequestIdHeader"
      - in: path
        name: datasetId
        description: Consignment dataset id in UUID format.
        schema:
          type: string
        required: true
      - in: query
        name: subsetId
        description: A set of subset ids. Must not be empty.
        schema:
          type: array
          uniqueItems: true
          items:
            type: string
        required: true
    get:
      operationId: "getConsignmentSubsets"
      responses:
        "200":
          description: Get the given consignment containing only the elements of the requested subsets
          content:
            application/xml:
              schema:
                type: object
                description: consignment element of type SupplyChainConsignment as defined by schema consignment-common.xsd
        default:
          description: Unexpected error
          content:
            application/problem+xml:
              schema:
                $ref: "#/components/schemas/ProblemDetail"

  /v0/consignments/{datasetId}/follow-up:
    parameters:
      - $ref: "#/components/parameters/RequestIdHeader"
      - in: path
        name: datasetId
        description: Consignment dataset id in UUID format.
        schema:
          type: string
        required: true
      - in: query
        name: uilQueryRequestId
        description: The X-Request-ID of a previous getConsignmentSubsets request.
        schema:
          type: string
          format: uuid
        required: true
    post:
      operationId: "postConsignmentFollowUp"
      summary: |
        Receive follow-up. Note that for traceability reasons, a getConsignmentSubsets request must have been performed 
        first. Then, a follow-up can be lodged referencing the getConsignmentSubsets by its X-Request-ID.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              description: XML of type FollowUpRequest as defined by platform.xsd
      responses:
        "200":
          description: Follow-up added to consignment