swagger: "2.0"
info:
  title: Open API Registry
  version: "0.1.0"
  description: |
    The registry contains Open API definitions for Temando Services and
    for the entire Platform.
consumes:
  - application/json
produces:
  - application/json
parameters:
  apiHandle:
    name: apiHandle
    in: path
    type: string
    description: The API name, expressed as a handle or slug, eg. `pet-store`.
    pattern: /[a-z0-9\-]+/
    required: true
  apiVersion:
    name: apiVersion
    in: path
    type: string
    description: The API version, eg. `0.1.0`.
    required: true
paths:
  /definitions:
    get:
      tags:
        - definitions
      summary: Return information about all APIs in the registry.
      responses:
        200:
          description: Successful response
          examples:
            application/json: |-
              [
                  {
                      "name": "Public API",
                      "handle": "public-api",
                      "version": "0.1.0"
                  },
                  {
                      "name": "Public API",
                      "handle": "public-api",
                      "version": "0.2.0"
                  },
                  {
                      "name": "Address API",
                      "handle": "address-api",
                      "version": "0.2.0"
                  }
              ]
          schema:
            type: array
            items:
              $ref: '#/definitions/apiDefinition'
  /definition/{apiHandle}:
    get:
      tags:
        - definition
      summary: Return information about definitions for the requested API.
      parameters:
        - $ref: '#/parameters/apiHandle'
      responses:
        200:
          description: Successful response
          examples:
            application/json: |-
              [
                  {
                      "name": "Public API",
                      "handle": "public-api",
                      "version": "0.1.0"
                  },
                  {
                      "name": "Public API",
                      "handle": "public-api",
                      "version": "0.2.0"
                  }
              ]
          schema:
            type: array
            items:
              $ref: '#/definitions/apiDefinition'
        404:
          description: API not found.
          examples:
            application/json: |-
              {
                "code": "404",
                "title": "API Not Found."
              }
          schema:
            $ref: '#/definitions/error'
  /definition/{apiHandle}/versions:
    get:
      tags:
        - definition
      summary: Return available versions of definitions for the requested API.
      parameters:
        - $ref: '#/parameters/apiHandle'
      responses:
        200:
          description: Successful response
          examples:
            application/json: |-
              [
                "0.1.0",
                "0.2.0"
              ]
          schema:
            type: array
            items:
              type: string
              example: "0.1.0"
        404:
          description: API not found.
          examples:
            application/json: |-
              {
                "code": "404",
                "title": "API Not Found."
              }
          schema:
            $ref: '#/definitions/error'
  /definition/{apiHandle}/versions/{apiVersion}:
    get:
      tags:
        - definition
      summary: |
        Return an Open API definition specified by the API handle and version.
      parameters:
        - $ref: '#/parameters/apiHandle'
        - $ref: '#/parameters/apiVersion'
      responses:
        200:
          description: Successful response
          examples:
            description: |
              The Open API definition for the requested API.
            application/json: |-
              {
                "swagger": "2.0",
                "info": {
                  "version": "1.0.0",
                  "title": "Swagger Petstore"
                }
                ...
              }
          schema:
            type: object
            description: The full Open API definition of this API, as a string of JSON or YAML.
            externalDocs:
              description: "The Open API specification."
              url: http://swagger.io/specification/
        404:
          description: API not found.
          examples:
            application/json: |-
              {
                "code": "404",
                "title": "API Not Found."
              }
          schema:
            $ref: '#/definitions/error'
definitions:
  apiDefinition:
    type: object
    required:
      - name
      - handle
      - version
    properties:
      name:
        type: string
        description: The name of the API the definition is documenting.
      handle:
        type: string
        description: The API name, expressed as a handle or slug, eg. `pet-store`.
        pattern: /[a-z0-9\-]+/
      version:
        type: string
        description: The version of the API the definition refers to.
  error:
    type: object
    description: A subset of the JSON API errors format.
    externalDocs:
      url: http://jsonapi.org/format/#errors
    properties:
      code:
        type: string
        description: |
          an application-specific error code, expressed as a string value.
      title:
        type: string
        description: |
          a short, human-readable summary of the problem that SHOULD NOT
          change from occurrence to occurrence of the problem, except
          for purposes of localization.