swagger.yaml

openapi: 3.0.0
info:
  title: VATSIM Canada
  version: '2.0'
  description: >-
    Documentation of the VATCAN API. Most endpoints are restricted to FIRs
    within the division.
  contact:
    email: tech@vatcan.ca
externalDocs:
  description: Generate your FIR's API Key
  url: https://vatcan.ca/manage/facilities
servers:
  - url: https://vatcan.ca/api
tags:
  - name: v2
  - name: user
  - name: facility
  - name: division
  - name: events
paths:
  /events:
    get:
      summary: Returns list of next 5 events (for home page).
      tags:
        - events
      security: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
  /v2/user/{cid}:
    get:
      summary: Returns a user's details by their CID.
      tags:
        - user
        - v2
      security:
        - AuthorizationHeader: []
        - QueryString: []
      parameters:
        - in: path
          name: cid
          schema:
            type: integer
          required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    enum:
                      - User fetched successfully.
                  data:
                    $ref: '#/components/schemas/UserWithFIR'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - This user does not exist.
                      - This facility does not exist.
        '401.1':
          $ref: '#/components/responses/AuthorizationWithoutToken'
        '401.2':
          $ref: '#/components/responses/NoApiKey'
        '401.3':
          $ref: '#/components/responses/InvalidApiKey'
  /v2/user/{cid}/notes:
    get:
      summary: >-
        Returns a user's notes by their CID. Please note this endpoint only
        returns training notes made by your FIR.
      tags:
        - user
        - v2
      security:
        - AuthorizationHeader: []
        - QueryString: []
      parameters:
        - in: path
          name: cid
          schema:
            type: integer
          required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    enum:
                      - Notes fetched successfully.
                  notes:
                    type: array
                    items:
                      $ref: '#/components/schemas/TrainingNote'
        '403':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - >-
                        You do not have permission to view this controllers
                        notes.
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - This user does not exist.
                      - This facility does not exist.
        '401.1':
          $ref: '#/components/responses/AuthorizationWithoutToken'
        '401.2':
          $ref: '#/components/responses/NoApiKey'
        '401.3':
          $ref: '#/components/responses/InvalidApiKey'
  /v2/user/{cid}/notes/create:
    post:
      summary: Create a new training note for a user.
      tags:
        - user
        - v2
      security:
        - AuthorizationHeader: []
        - QueryString: []
      parameters:
        - in: path
          name: cid
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                instructor_cid:
                  type: integer
                position:
                  type: string
                note:
                  type: string
                session_type:
                  type: integer
                  pattern: '[0-3]'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    enum:
                      - Training note created.
                  sandbox:
                    type: boolean
                    example: false
                    description: True if a sandbox API key was used.
        '400':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - Validation failure.
                  hint:
                    type: array
                    items: {}
        '403':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - >-
                        You do not have permission to view this controllers
                        notes.
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - This user does not exist.
                      - This facility does not exist.
        '401.1':
          $ref: '#/components/responses/AuthorizationWithoutToken'
        '401.2':
          $ref: '#/components/responses/NoApiKey'
        '401.3':
          $ref: '#/components/responses/InvalidApiKey'
  /v2/facility/roster:
    get:
      summary: Returns FIR's roster.
      tags:
        - facility
        - v2
      security:
        - AuthorizationHeader: []
        - QueryString: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    enum:
                      - Fetched successfully
                  data:
                    type: object
                    properties:
                      facility:
                        $ref: '#/components/schemas/Facility'
                      staff:
                        type: object
                        properties:
                          chief:
                            $ref: '#/components/schemas/User'
                          deputy:
                            type: object
                          ci:
                            type: object
                          ec:
                            type: object
                          fe:
                            type: object
                          wm:
                            type: object
                      controllers:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
                      visitors:
                        type: array
                        items:
                          $ref: '#/components/schemas/UserWithFIR'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - This facility does not exist.
        '401.1':
          $ref: '#/components/responses/AuthorizationWithoutToken'
        '401.2':
          $ref: '#/components/responses/NoApiKey'
        '401.3':
          $ref: '#/components/responses/InvalidApiKey'
  /v2/facility/activity:
    get:
      summary: Returns FIR's activity from last 4 weeks.
      tags:
        - facility
        - v2
      security:
        - AuthorizationHeader: []
        - QueryString: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    enum:
                      - Fetched successfully.
                  data:
                    type: object
                    properties:
                      cid:
                        type: array
                        items:
                          $ref: '#/components/schemas/Activity'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - This facility does not exist.
        '401.1':
          $ref: '#/components/responses/AuthorizationWithoutToken'
        '401.2':
          $ref: '#/components/responses/NoApiKey'
        '401.3':
          $ref: '#/components/responses/InvalidApiKey'
  /v2/facility/events:
    get:
      summary: Returns all FIR events.
      tags:
        - facility
        - v2
      security:
        - AuthorizationHeader: []
        - QueryString: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    enum:
                      - Fetched successfully.
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
        '404':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    enum:
                      - This facility does not exist.
        '401.1':
          $ref: '#/components/responses/AuthorizationWithoutToken'
        '401.2':
          $ref: '#/components/responses/NoApiKey'
        '401.3':
          $ref: '#/components/responses/InvalidApiKey'
  /v2/division/events:
    get:
      summary: Returns list of next 15 events.
      tags:
        - division
        - v2
      security: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    enum:
                      - Fetched successfully
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
components:
  schemas:
    Event:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        start:
          type: string
        end:
          type: string
        airports:
          type: object
          properties:
            arrival:
              type: array
              nullable: true
              example:
                - CYYZ
                - CYVR
              items:
                type: string
            departure:
              type: array
              nullable: true
              example: null
              items:
                type: string
        forum_event_id:
          type: integer
          description: Event ID on forums.vatcan.ca
        facilities:
          type: integer
          description: Bitmap of the VATCAN FIRs responsible for the event.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        forum_url:
          type: string
        start_pretty:
          type: string
        end_pretty:
          type: string
    User:
      type: object
      properties:
        cid:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        facility:
          type: integer
          description: ID of the user's FIR.
        facility_join:
          type: string
        rating:
          type: integer
          description: User's VATSIM rating.
        last_active:
          type: string
          description: Last time user accessed website.
        flag_basic:
          type: boolean
          description: True if user has not completed Basic ATC Exam.
        flag_is_visitor:
          type: boolean
          description: True if user is outside of VATCAN.
        flag_xferOverride:
          type: boolean
          description: >-
            True if user has been granted a transfer override (to avoid
            restrictions).
        last_api_check:
          type: string
          description: Last time user was against VATSIM's API.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        email_preferences:
          type: integer
          description: Bitmap of user's email preferences.
    UserWithFIR:
      allOf:
        - $ref: '#/components/schemas/User'
        - properties:
            fir:
              type: object
              $ref: '#/components/schemas/Facility'
    Facility:
      type: object
      properties:
        id:
          type: integer
          description: ID of the FIR.
        name_long:
          type: string
        name_short:
          type: string
        website_url:
          type: string
        fir_description:
          type: string
        is_fir:
          type: boolean
          description: True if it is a real facility.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    TrainingNote:
      type: object
      properties:
        id:
          type: integer
        cid:
          type: integer
        instructor_cid:
          type: integer
        facility_id:
          type: integer
          description: ID of the FIR the note was created in.
        training_note:
          type: string
        session_type:
          type: integer
          enum:
            - 0
            - 1
            - 2
            - 3
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        friendly_time:
          type: string
          format: date
        instructor_name:
          type: string
    Activity:
      type: object
      properties:
        id:
          type: integer
        user_cid:
          type: integer
        time:
          type: string
          description: Time in minutes that the user has controlled in your facility.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    AuthorizationHeader:
      type: apiKey
      name: Authorization
      in: header
      description: 'For this type of authentication, follow the format: `Token [api_key]`.'
    QueryString:
      type: apiKey
      name: api_key
      in: query
  responses:
    AuthorizationWithoutToken:
      description: Authorization header without token provided.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                  - Invalid API key.
              message:
                type: string
                enum:
                  - >-
                    Authorization header was provided, but the provided value
                    did not prefix with "Token".
    NoApiKey:
      description: No API key found in request.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                  - Invalid API key.
              message:
                type: string
                enum:
                  - >-
                    No API key was found in the body, or query params of the
                    request. If you are attempting to use the Authorization
                    header, it was not included in your request.
    InvalidApiKey:
      description: API key does not exist.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                  - Invalid API key.
              api_key:
                type: string