swagger: '2.0'
info:
  title: MAX
  version: 0.1.0
  description: MAX PC-MID API
host: localhost:10098
basePath: /
schemes: [https]

tags:
- name: enrol
  description: Enrol an application so that it can use the MAX API.
- name: roles
  description: Fetch and request roles information.

paths:
  /MAXAPI/venue-api-root-cert:
    get:
      tags: [enrol]
      summary: Establish trust between client and server
      description: |
        The purpose of visiting this endpoint is to retrieve the Root CA of this server's certificate. This is provided so that the client can store the Root CA certificate in it's trusted key store.

        When making a request, the client should not verify the server's certificate against a list of certificate authorities (CAs).
      responses:
        200:
          $ref: '#/responses/CACertificate'
  /enrol:
    get:
      tags: [enrol]
      summary: Establish trust between client and server
      description: |
        The purpose of visiting this endpoint is to make an initial request to allow the client and server to handshake, so that the client can use the previously retrieved CA to verify the Server's certificate.
        
      responses:
        204:
          description: No content
    post:
      tags: [enrol]
      summary: Enrol with the client's CSR
      description: The purpose of visiting this endpoint is to allow the client to upload a certificate signing request (CSR) and for the server to return a signed certificate to allow secure communication.
      consumes: [application/pkcs10]
      produces: [application/x-x509-ca-cert, application/x-pem-file]
      parameters:
      - in: body
        name: csr
        description: CSR (certificate signing request)
        required: true
        schema:
          type: string
      responses:
        201:
          description: Enrolment successful
          schema:
            type: file
        400:
          $ref: '#/responses/InvalidCSR'
        406:
          $ref: '#/responses/CertTypeNotAcceptable'

  /roles:
    get:
      tags: [roles]
      summary: Fetch information on roles 
      description: This purpose of visiting this endpoint is to allow the client to find out the status as to whether or not the requested roles have been granted or not.
      responses:
        200:
          $ref: '#/responses/RolesResponse'
        403:
          $ref: '#/responses/AccessDenied'
        404:
          $ref: '#/responses/NotFound'
    post:
      tags: [roles]
      summary: Request roles
      description: This purpose of visiting this endpoint is to allow the client to request roles that will provide appropriate permission for the third party application type.
      consumes: [application/json]
      produces: [application/json]
      parameters:
      - in: body
        name: roles
        description: Roles requested by the client
        schema:
          $ref: '#/definitions/RolesRequest'
      responses:
        201:
          $ref: '#/responses/RolesResponse'
        400:
          $ref: '#/responses/RolesBadRequest'
        403:
          $ref: '#/responses/AccessDenied'

responses:
  CACertificate:
    description: CA certificate
    schema:
      $ref: '#/definitions/CAResponse'
  RolesResponse:
    description: Get roles and permissions info
    schema:
      $ref: '#/definitions/RolesResponse'
  AccessDenied:
    description: User does not have access to page
    schema:
      $ref: '#/definitions/AccessDenied'
  RolesBadRequest:
    description: Bad request
    schema:
      $ref: '#/definitions/APIError'
  NotFound:
    description: Not found
    schema:
      $ref: '#/definitions/APIError'
  InvalidCSR:
    description: Invalid CSR
    schema:
      $ref: '#/definitions/APIError'
  CertTypeNotAcceptable:
    description: Certificate type is not acceptable
    schema:
      $ref: '#/definitions/APIError'

definitions:
  AccessDenied:
    type: string
  RolesRequest:
    type: object
    required:
      - roles
    properties:
      roles:
        $ref: '#/definitions/RolesRequestRoles'
    example:
      roles:
        - superuser
        - venue-api-consumer

  RolesRequestRoles:
    type: array
    items:
      type: string

  APIError:
    type: object
    required:
      - status
      - title
      - detail
    properties:
      status:
        type: string
        description: HTTP status text description
      title:
        type: string
        description: Quick description of the error
      detail:
        type: string
        description: More detail on the error
  CAResponse:
    type: string
  RolesResponse:
    type: object
    properties:
      roles:
        $ref: '#/definitions/RolesResponseRoles'
    example:
      roles:
        approved: [venue-api-consumer]
        desired: [jackpot]

  RolesResponseRoles:
    type: object
    properties:
      approved:
        type: array
        items:
          type: string
      desired:
        type: array
        items:
          type: string