openapi: 3.1.0
info:
  version: "3.0.0"
  title: Platform Server
  description: |
    The platform server is an internal component. It should be hosted in a private network and should not be accessible from the Internet. This server enables the business to fetch and update the state of transactions using its API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://platform-server.exampleanchor.com
tags:
  - name: "Transactions"
    description: "Transactions initiated by client applications via SEP APIs"
paths:
  /transactions:
    get:
      tags:
        - "Transactions"
      x-seps:
        - SEP-6
        - SEP-24
        - SEP-31
      summary: Retrieve a List of Transactions
      operationId: getTransactions
      description:
        Allows to query list of transactions for desired SEP. This api supports pagination, and it's possible (and recommended) to make multiple requests to query transactions.
        The last page is reached when the number of elements returned by the endpoint is smaller than provided `page_size`.
      parameters:
        - in: query
          name: sep
          required: true
          schema:
            type: string
            enum: [ "6", "24", "31" ]
          description:
            Lookup transactions belonging to this SEP.
        - in: query
          name: order_by
          schema:
            type: string
            enum: [ created_at, transfer_received_at, user_action_required_by ]
            default: created_at
          description:
            Specifies field that transactions will be ordered by. Note, that secondary sort is transaction id in ascending value.

            I.e. when timestamps for 2 or more transactions is identical, they will be sorted by id.
        - in: query
          name: order
          schema:
            type: string
            enum: [ asc, desc ]
            default: asc
          description:
            Specifies order. Note, that when the field is null, all transactions with null value will be last, regardless of soring order (NULLS LAST).

            For example, transfer time may not be specified for some transactions, resulting into `transfer_received_at` being null. If so, transactions with non-null values will be sorted and returned first, followed by all transactions with null timestamps.
        - in: query
          name: statuses
          schema:
            type: array
            items:
              $ref: './schemas.yaml#/components/schemas/StatusSEPAll'
          description: Filters transactions for specified array of statuses. If not provided, filtering is disabled (default behavior)
        - in: query
          name: page_size
          schema:
            type: integer
            default: 20
          description:
            Size of a single search page. Must be positive.
        - in: query
          name: page_number
          schema:
            type: integer
            default: 0
          description:
            Page number to use for continuous search. Page count beings at 0.
      responses:
        '200':
          description: "Transaction found."
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: './schemas.yaml#/components/schemas/TransactionListSEP6'
                  - $ref: './schemas.yaml#/components/schemas/TransactionListSEP24'
                  - $ref: './schemas.yaml#/components/schemas/TransactionListSEP31'
        '400':
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: './schemas.yaml#/components/schemas/Error'
        '404':
          description: "Transaction not found."
          content:
            application/json:
              schema:
                $ref: './schemas.yaml#/components/schemas/Error'
  /transactions/{id}:
    get:
      tags:
        - "Transactions"
      x-seps:
        - SEP-6
        - SEP-24
        - SEP-31
      summary: Retrieve a Transaction
      operationId: getTransaction
      description:
        Provides the information necessary for the business to determine the state of the transaction identified by
        `id`, decide if any action must be taken to continue processing the transaction, and act on the decision.
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "Transaction found."
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: './schemas.yaml#/components/schemas/TransactionSEP6'
                  - $ref: './schemas.yaml#/components/schemas/TransactionSEP24'
                  - $ref: './schemas.yaml#/components/schemas/TransactionSEP31'
        '400':
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: './schemas.yaml#/components/schemas/Error'
        '404':
          description: "Transaction not found."
          content:
            application/json:
              schema:
                $ref: './schemas.yaml#/components/schemas/Error'

# CHANGELOG
## v2.0.0: Simplified the Event by merging the QuoteEvent and Transaction Event and embedding the detail in the `transaction` and `quote` field. Removed unused schemas.