openapi: 3.0.3
info:
  title: Online Teaching Connector
  version: 1.0.1
  contact:
    name: Eveoh Support
    url: 'https://developer.eveoh.nl'
    email: support@eveoh.nl
  description: |-
    The Online Teaching Connector application provides a holding page for Microsoft Teams and Zoom meetings. It can also create Microsoft Teams and Zoom meetings on behalf of authorised users.

    # Authentication
    The current Online Teaching Connector API only supports Bearer authentication using an API key. Make sure to keep your authentication details secure. Do not share your authentication details in publicly accessible areas such as GitHub, client-side code, and so forth.

    All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

    Please contact support to request an API key.

    <security-definitions />

    # Errors
    HTTP response codes are used to indicate the success or failure of an API request. The following response codes can be expected:
    - 2xx codes indicate success
    - 4xx codes indicate client errors (e.g., a required parameter is missing, the requested object does not exist, etc.)
    - 5xx codes indicate server errors on the Online Teaching Connector side

    Most general response codes, such as `405 Method Not Allowed` are not documented per call. The following general response codes can be returned by the API:

    - 401 Unauthorized
    - 403 Forbidden
    - 405 Method Not Allowed
    - 406 Not Acceptable
    - 415 Unsupported Media Type

    If any response code have a specific meaning for a certain call, they are documented as such with the call.

    Error responses either return an empty body, or a body with content type `application/json` structured as follows:

    <SchemaDefinition schemaRef="#/components/schemas/Error" />

    # Dates and times
    All dates and times are represented in the `RFC 3339` format.

    Please note that `date-time` values can be returned in any offset, e.g. `Z` (UTC) or something like `+01:00`.
servers:
  - description: Production
    url: 'https://{tenant}.meeting.mytimetable.net/api/v1'
    variables:
      tenant:
        default: tenantCode
        description: Identifier for the given tenant.
  - url: 'https://{tenant}-acc.meeting.mytimetable.net/api/v1'
    description: Acceptance
    variables:
      tenant:
        default: tenantCode
        description: Identifier for the given tenant.
  - url: 'https://meeting.localhost:8080/api/v1'
    description: Development
paths:
  /meetings:
    get:
      summary: List meetings
      tags:
        - Meeting
      operationId: get-meetings
      parameters:
        - $ref: '#/components/parameters/MeetingFrom'
        - $ref: '#/components/parameters/MeetingTo'
      description: List all the meetings that have been created.
      responses:
        '200':
          $ref: '#/components/responses/MeetingCollectionResponse'
        '401':
          description: Unauthorized
      security:
        - http_bearer_auth:
            - 'meeting:read'
  '/meetings/{id}':
    parameters:
      - $ref: '#/components/parameters/MeetingId'
    get:
      summary: Get a meeting
      tags:
        - Meeting
      responses:
        '200':
          $ref: '#/components/responses/MeetingResponse'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/MeetingNotFoundResponse'
      operationId: get-meeting-instance
      description: Retrieve the details of a meeting.
      parameters: []
      security:
        - http_bearer_auth:
            - 'meeting:read'
  /meetingPlatforms:
    get:
      summary: List meeting platforms
      tags:
        - MeetingPlatform
      operationId: get-meetingPlatforms
      description: |-
        List all the meeting platforms that are supported. 

        Not all meeting platforms might be enabled for a tenant.
      responses:
        '200':
          $ref: '#/components/responses/MeetingPlatformCollectionResponse'
        '401':
          description: Unauthorized
      parameters: []
      security:
        - http_bearer_auth:
            - 'meeting-platform:read'
  /meetingActions:
    get:
      summary: List meeting actions
      tags:
        - MeetingAction
      operationId: get-meetingactions
      parameters:
        - $ref: '#/components/parameters/MeetingActionFrom'
        - $ref: '#/components/parameters/MeetingActionTo'
      description: |-
        List all the meeting actions.

        Meeting actions are actions performed by a user for a given meeting, such as creating or joining the meeting.
      responses:
        '200':
          $ref: '#/components/responses/MeetingActionCollectionResponse'
        '401':
          description: Unauthorized
      security:
        - http_bearer_auth:
            - 'meeting-action:read'
  '/meetingActions/{id}':
    parameters:
      - $ref: '#/components/parameters/MeetingActionId'
    get:
      summary: Get a meeting action
      tags:
        - MeetingAction
      responses:
        '200':
          $ref: '#/components/responses/MeetingActionResponse'
        '401':
          description: Unauthorized
        '404':
          $ref: '#/components/responses/MeetingActionNotFoundResponse'
      operationId: get-meeting-action-instance
      description: Retrieve the details of a meeting action.
      parameters: []
      security:
        - http_bearer_auth:
            - 'meeting-action:read'
components:
  schemas:
    Meeting:
      title: Meeting
      type: object
      description: Meeting object.
      properties:
        id:
          type: integer
          example: 34564
          description: The unique identifier of the meeting.
          minimum: 1
        meetingPlatform:
          $ref: '#/components/schemas/MeetingPlatform'
        externalId:
          type: string
          example: 03808328FFA64B0EBCD221737B945E89-2020-12-15
          description: 'The external identifier used to identify the meeting, used to link to the meeting page.'
        meetingId:
          type: string
          description: The unique identifier used by the meeting platform to refer to this meeting.
          example: dGhlbWVldGluZ2lkZW50aWZpZXI=
        subject:
          type: string
          example: IT101 Introduction into Microsoft Teams
          description: The subject of the meeting.
          nullable: true
        start:
          type: string
          format: date-time
          example: '2020-12-15T10:00:00+02:00'
          description: The (inclusive) start time of the meeting.
        end:
          type: string
          format: date-time
          example: '2020-12-15T12:00:00+02:00'
          description: The (exclusive) end time of the meeting.
        participantJoinUrl:
          type: string
          format: uri
          description: The URL that can be used by participants to join the meeting on the given meeting platform.
          example: 'https://example.org/join-meeting/dGhlbWVldGluZ2lkZW50aWZpZXI='
        created:
          format: date-time
          example: '2020-12-15T09:47:21+02:00'
          description: Creation time of the meeting.
          type: string
        createdBy:
          type: string
          description: |-
            The user that created the meeting.

            Meetings that have been created before the introduction of this property have a `null` value.
          minLength: 1
          maxLength: 128
          nullable: true
          example: john.doe@example.org
      required:
        - id
        - meetingPlatform
        - externalId
        - meetingId
        - start
        - end
        - participantJoinUrl
        - created
    MeetingPlatform:
      title: MeetingPlatform
      type: object
      properties:
        id:
          type: string
          example: TEAMS
          description: The unique identifier of this meeting platform.
      required:
        - id
      description: Meeting Platform object.
    MeetingAction:
      title: MeetingAction
      type: object
      description: Meeting Action object.
      properties:
        id:
          type: integer
          format: uuid
          example: 234453
          description: The unique identifier of this meeting action.
          minimum: 1
        meeting:
          $ref: '#/components/schemas/Meeting'
        user:
          type: object
          description: The user that performed the action.
          required:
            - username
          properties:
            username:
              type: string
              minLength: 1
              example: john.doe@example.org
              maxLength: 128
        action:
          type: string
          enum:
            - JOIN
            - CREATE
          description: The action that was performed by the user.
          minLength: 1
          maxLength: 32
        timestamp:
          type: string
          format: date-time
          description: Time the action was performed.
          example: '2020-12-15T09:58:23+02:00'
      required:
        - id
        - meeting
        - user
        - action
        - timestamp
    Error:
      title: Error
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: Time at which the error occurred.
          example: '2020-12-14T10:00:43.695+00:00'
        status:
          type: integer
          description: The HTTP error code.
          example: 404
        error:
          type: string
          description: A human-readable description of the HTTP error code.
          example: Not Found
        message:
          type: string
          description: A human-readable message providing more details about the error.
          example: Meeting could not be found
        path:
          type: string
          description: The path that was called.
          example: /api/v1/meetings/1
      required:
        - status
      description: Error object.
  responses:
    MeetingResponse:
      description: OK. Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Meeting'
    MeetingCollectionResponse:
      description: OK. Successful response.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Meeting'
    MeetingActionResponse:
      description: OK. Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MeetingAction'
    MeetingActionCollectionResponse:
      description: OK. Successful response.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/MeetingAction'
    MeetingPlatformCollectionResponse:
      description: OK. Successful response.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/MeetingPlatform'
          example:
            - id: TEAMS
            - id: ZOOM
    MeetingNotFoundResponse:
      description: Not Found. Meeting could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            timestamp: '2020-12-14T10:00:43.695+00:00'
            status: 404
            error: Not Found
            message: Meeting could not be found
            path: /api/v1/meetings/34564
    MeetingActionNotFoundResponse:
      description: Not Found. Meeting action could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            timestamp: '2020-12-14T10:00:43.695+00:00'
            status: 404
            error: Not Found
            message: Meeting action could not be found
            path: /api/v1/meetingActions/234453
  parameters:
    MeetingId:
      name: id
      in: path
      required: true
      schema:
        type: number
        example: 34564
      description: The unique identifier of the meeting.
    MeetingFrom:
      name: from
      in: query
      schema:
        type: string
        format: date-time
        example: '2020-01-01T00:00:00+02:00'
      description: The start of the date range over which you want to search (inclusive).
    MeetingTo:
      name: to
      in: query
      required: false
      schema:
        type: string
        format: date-time
        example: '2020-12-18T00:00:00+02:00'
      description: The end of the date range over which you want to search (exclusive).
    MeetingActionId:
      name: id
      in: path
      required: true
      schema:
        type: number
        example: 34564
      description: The unique identifier of the meeting action.
    MeetingActionFrom:
      name: from
      in: query
      schema:
        type: string
        format: date-time
        example: '2020-01-01T00:00:00+02:00'
      description: The start of the date range over which you want to search (inclusive).
    MeetingActionTo:
      name: to
      in: query
      required: false
      schema:
        type: string
        format: date-time
        example: '2020-12-18T00:00:00+02:00'
      description: The end of the date range over which you want to search (exclusive).
  securitySchemes:
    http_bearer_auth:
      type: http
      scheme: bearer
      description: |-
        Opaque bearer token containing the API key. `Authorization` header should contain `Bearer <api-key>`.

        ### Access scopes

        Each API key is assigned zero or more scopes. The following scopes are supported:

        - `meeting:read` - Read meeting information
        - `meeting-action:read` - Read meeting action information
        - `meeting-platform:read` - Read meeting platform information
security:
  - http_bearer_auth: []
tags:
  - name: Meeting
    description: 'Meetings represent a meeting on a certain platform, such as Zoom or Teams, that has been created using the Online Teaching Connector.'
  - name: MeetingPlatform
    x-displayName: Meeting Platform
    description: 'A Meeting Platform represents a platform, such as Zoom or Teams, that is supported by the Online Teaching Connector to create meetings.'
  - name: MeetingAction
    x-displayName: Meeting Action
    description: 'Meeting actions are actions performed by a user for a given meeting, such as creating or joining a meeting. Actions such as joining can be performed multiple times by a user for a given meeting, i.e. re-joining a meeting.'
