openapi: "3.0.1"
info:
  title: MaitreD API
  version: 1.0.0
basePath: /api
x-mojo-name: api

servers:
  - url: http://tucha:3000/{basePath}
    description: The development API server
    variables:
      basePath:
        enum:
          - api
          - v1
          - v2
        default: api
  - url: http://production/{basePath}
    description: The production API server
    variables:
      basePath:
        default: api


paths:
  /countries:
    get:
      summary: List all countries
      operationId: list_countries
      x-mojo-to: 'country#list'
      tags:
        - countries
      responses:
        '200':
          description: Array of countries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Countries"
        default:
          $ref: '#/components/responses/Error'

    post:
      summary: Create a country
      operationId: create_country
      x-mojo-to: 'country#store'
      tags:
        - countries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Country'
                - required:
                  # For new record ID is generated by database
                  # - id
                  # We just require all NOT NULL fields:
                  - code
                  - default_language_id

      # When request is done we return new object or error
      responses:
        200:
          $ref: '#/components/responses/Country'
        default:
          $ref: '#/components/responses/Error'


  /countries/{id}:
    summary: Routes for country manipulation
    parameters:
      - $ref: '#/components/parameters/resourceID'
    get:
      summary: Get requested country
      operationId: show_country
      x-mojo-to: 'country#show'
      tags:
        - countries

      # When request is done we return requested object or error
      responses:
        200:
          $ref: '#/components/responses/Country'
        default:
          $ref: '#/components/responses/Error'

    put:
      summary: Update requested country
      operationId: update_country
      x-mojo-to: 'country#update'
      tags:
        - countries
      requestBody:
        description: Update country
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Country'
                # TODO: Find a place in SPEC where defined that type is required
                - type: object
                # We can update only one or more fields.
                # Empty requests or requests with not known fields are meaningless
                  minProperties: 1
                  additionalProperties: false
                # Here we list fields which are allowed to be updated:
                  properties:
                    code: {}
                    default_language_id: {}


      # When request is done we return updated object or error
      responses:
        200:
          $ref: '#/components/responses/Country'
        default:
          $ref: '#/components/responses/Error'

    delete:
      summary: Delete requested country
      operationId: delete_country
      x-mojo-to: 'country#delete'
      tags:
        - countries

      # When request is done we return success or error
      responses:
        302:
          description: Country was deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Success'
        default:
          $ref: '#/components/responses/Error'



components:
  schemas:
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string


    # TODO: Implement more robust success response
    Success:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string


    # Here we should describe a database object.
    # What fields are and which constraints they have
    Country:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        code:
          type: string
          minLength: 2
          maxLength: 2
        default_language_id:
          type: integer

    # And list of objects
    Countries:
      type: array
      items:
        $ref: "#/components/schemas/Country"


  responses:
    Error:
      description: unexpected error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    Country:
      description: Country object
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Country'
              # When we send object to client we MUST tell to client its identificator
              - required:
                - id


  # 'parameters' better to keep at bootom of schema.
  # Thus we can easily jump to and define new global parameter
  parameters:
    resourceID:
      description: Resource identificator
      in: path
      name: id
      required: true
      schema:
        type: integer
        format: int32

    formatParameter:
      description: Requested format
      in: query
      name: format
      required: false
      schema:
        type: string