annotationd.yml

openapi: 3.0.0
info:
  title: Annotations service
  version: 0.2.3
  license:
    name: MIT
    url: 'https://opensource.org/licenses/MIT'
servers:
  - url: /api/v2private
paths:
  /annotations:
    post:
      tags:
        - Annotations
      operationId: createAnnotations
      summary: Create annotations
      requestBody:
        description: Annotations to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationCreateList'
      responses:
        '200':
          description: Annotations created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationEventList'
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
    get:
      tags:
        - Annotations
      operationId: listAnnotations
      summary: List annotations
      parameters:
        - $ref: '#/components/parameters/AnnotationListFilter'
      responses:
        '200':
          description: Optionally filtered list of annotations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationList'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Annotations
      operationId: deleteAnnotations
      summary: Delete annotation
      parameters:
        - $ref: '#/components/parameters/AnnotationDeleteFilter'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
  '/annotations/{annotationID}':
    get:
      tags:
        - Annotations
      summary: Retrieve an annotation
      parameters:
        - in: path
          name: annotationID
          description: The identifier of the annotation.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The annotation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationEvent'
        '401':
          $ref: '#/components/responses/ServerError'
        '404':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
        default:
          $ref: '#/components/responses/ServerError'
    put:
      tags:
        - Annotations
      operationId: updateAnnotation
      summary: Update an annotation
      parameters:
        - in: path
          name: annotationID
          description: The identifier of the annotation.
          required: true
          schema:
            type: string
      requestBody:
        description: Annotation to store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationCreate'
      responses:
        '200':
          description: The updated annotation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationEvent'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '404':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Annotations
      operationId: deleteAnnotation
      summary: Delete an annotation by ID
      parameters:
        - in: path
          name: annotationID
          description: The identifier of the annotation.
          required: true
          schema:
            type: string
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
  /streams:
    put:
      tags:
        - Streams
      operationId: createUpdateStream
      summary: Create or update stream
      requestBody:
        description: Stream to create or update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Stream'
      responses:
        '200':
          description: Stream as created/updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadStream'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
    get:
      tags:
        - Streams
      operationId: getStreams
      summary: Get streams
      parameters:
        - $ref: '#/components/parameters/StreamListFilter'
      responses:
        '200':
          description: Optionally filtered list of streams
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamList'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Streams
      operationId: deleteStream
      summary: Delete stream
      parameters:
        - $ref: '#/components/parameters/StreamDeleteFilter'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
  '/streams/{streamID}':
    put:
      tags:
        - Streams
      operationId: updateStream
      summary: Update stream
      parameters:
        - in: path
          name: streamID
          description: stream to update
          required: true
          schema:
            type: string
      requestBody:
        description: Stream to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Stream'
      responses:
        '200':
          description: Stream as updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadStream'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '404':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Streams
      operationId: deleteStreamByID
      summary: Delete stream by ID
      parameters:
        - in: path
          name: streamID
          description: stream to delete
          required: true
          schema:
            type: string
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/ServerError'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    AnnotationListFilter:
      in: query
      name: AnnotationListFilter
      required: false
      description: Filter for returned annotations
      schema:
        $ref: '#/components/schemas/AnnotationListFilter'
    AnnotationDeleteFilter:
      in: query
      name: AnnotationDeleteFilter
      required: true
      description: Annotations to delete
      schema:
        $ref: '#/components/schemas/AnnotationDeleteFilter'
    StreamListFilter:
      in: query
      name: StreamListFilter
      required: false
      description: Filter for returned streams
      schema:
        $ref: '#/components/schemas/StreamListFilter'
    StreamDeleteFilter:
      in: query
      name: StreamDeleteFilter
      required: true
      description: Stream to delete
      schema:
        $ref: '#/components/schemas/StreamDeleteFilter'
  schemas:
    AnnotationListFilter:
      allOf:
        - $ref: '#/components/schemas/BasicFilter'
        - type: object
          properties:
            stickerIncludes:
              type: object
              additionalProperties:
                type: string
            streamIncludes:
              type: array
              items:
                type: string
    AnnotationDeleteFilter:
      type: object
      required:
        - stream
        - startTime
        - endTime
      properties:
        stickers:
          type: object
          additionalProperties:
            type: string
        stream:
          type: string
        streamID:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
    BasicFilter:
      type: object
      properties:
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
    AnnotationList:
      type: array
      items:
        type: object
        properties:
          stream:
            type: string
          annotations:
            type: array
            items:
              $ref: '#/components/schemas/AnnotationResponse'
    AnnotationEventList:
      type: array
      items:
        $ref: '#/components/schemas/AnnotationEvent'
    AnnotationEvent:
      allOf:
        - $ref: '#/components/schemas/Annotation'
        - type: object
          properties:
            stream:
              type: string
            id:
              type: string
    AnnotationCreateList:
      type: array
      items:
        $ref: '#/components/schemas/AnnotationCreate'
    AnnotationCreate:
      allOf:
        - $ref: '#/components/schemas/Annotation'
        - type: object
          properties:
            stream:
              type: string
    Annotation:
      type: object
      properties:
        summary:
          type: string
        message:
          type: string
        stickers:
          type: object
          additionalProperties:
            type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
    AnnotationResponse:
      type: object
      properties:
        id:
          type: string
        summary:
          type: string
        message:
          type: string
        stickers:
          type: object
          additionalProperties:
            type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
    StreamListFilter:
      allOf:
        - $ref: '#/components/schemas/BasicFilter'
        - type: object
          properties:
            streamIncludes:
              type: array
              items:
                type: string
            allStreams:
              type: boolean
    StreamDeleteFilter:
      type: object
      properties:
        stream:
          type: string
    StreamList:
      type: array
      items:
        $ref: '#/components/schemas/ReadStream'
    Stream:
      type: object
      properties:
        stream:
          type: string
        description:
          type: string
    ReadStream:
      type: object
      properties:
        id:
          type: string
        stream:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      properties:
        code:
          description: code is the machine-readable error code.
          readOnly: true
          type: string
          enum:
            - internal error
            - not implemented
            - not found
            - conflict
            - invalid
            - unprocessable entity
            - empty value
            - unavailable
            - forbidden
            - too many requests
            - unauthorized
            - method not allowed
            - request too large
            - unsupported media type
        message:
          readOnly: true
          description: Human-readable message.
          type: string
        op:
          readOnly: true
          description: Describes the logical code operation when the error occurred. Useful for debugging.
          type: string
        err:
          readOnly: true
          description: Stack of errors that occurred during processing of the request. Useful for debugging.
          type: string
      required:
        - code
  responses:
    NoContent:
      description: No content
    ServerError:
      description: Non 2XX error response from server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'