swagger

openapi: 3.0.0
servers:
  - url: 'http://localhost/vbc/rdw'
info:
  version: 1.0.1
  title: RDW API
  description: An API to manipulate the contents and behavior of the RDW
paths:
  /login:
    post:
      summary: Login
      tags:
        - login
      security: []
      description: Authenticating towards VBC to receive the Session cookie
      requestBody:
        content:
          application/json:
            schema:
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  example: admin
                password:
                  type: string
                  example: elvis
        description: Valid VBC account credentials
        required: true
      responses:
        '204':
          headers:
            Set-Cookie:
              description: Session
              schema:
                type: string
          description: >
            Successfully authenticated. The session ID is returned in a cookie
            named `Session`. You need to include this cookie in subsequent
            requests. The session is valid for 5 minutes, after this, you need
            to log in again.
        '400':
          description: Invalid parameters
        '401':
          description: Incorrect username and/or password
        '503':
          description: Unable to log in
  /devices:
    get:
      summary: Get list of devices
      tags:
        - devices
      description: Returns a list of all devices accessable by the authenticated user
      responses:
        '200':
          description: A list of Device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Devices'
  '/devices/{uuid}':
    patch:
      summary: Update device
      tags:
        - devices
      description: Change what canvas is displayed on a device
      parameters:
        - $ref: '#/components/parameters/uuid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Device'
        description: Device properties to update
      responses:
        '204':
          description: Update completed
        '400':
          description: Invalid parameters
        '403':
          description: Authenticated user does not have access to this device
        '404':
          description: Canvas does not exist
        '503':
          description: 'Could not update database, try again later'
  /canvas:
    get:
      summary: Get list of canvases
      tags:
        - canvas
      description: Returns a list of all canvases accessable by the authenticated user
      responses:
        '200':
          description: A list of Canvas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Canvases'
  '/canvas/{canvasId}/widgets':
    get:
      summary: Get map of widgets
      tags:
        - canvas
      description: Returns a map of all widgets on specified canvas
      parameters:
        - $ref: '#/components/parameters/canvasId'
      responses:
        '200':
          description: A map of widgetId to Widget
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widgets'
        '403':
          description: Authenticated user does not have access to this canvas
        '404':
          description: Canvas does not exist
  '/canvas/{canvasId}/{widgetId}':
    patch:
      summary: Update widget
      tags:
        - canvas
      description: Change widget configuration
      parameters:
        - $ref: '#/components/parameters/canvasId'
        - $ref: '#/components/parameters/widgetId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WidgetPatchExample'
        description: Parameters that will be updated
      responses:
        '200':
          description: Update completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Widget'
        '400':
          description: Invalid parameters
        '403':
          description: Authenticated user does not have access to this canvas
        '404':
          description: Canvas or widget does not exist
        '409':
          description: Serial mismatch
        '503':
          description: 'Could not update database, try again later'
security:
  - sessionAuth: []
components:
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: cookie
      name: Session
  parameters:
    session:
      name: Session
      in: cookie
      required: true
      description: The session cookie
      schema:
        type: string
    uuid:
      name: uuid
      in: path
      required: true
      description: The device's UUID
      schema:
        type: string
    canvasId:
      name: canvasId
      in: path
      required: true
      description: The canvas' ID
      schema:
        type: integer
    widgetId:
      name: widgetId
      in: path
      required: true
      description: The widget's ID
      schema:
        type: integer
  schemas:
    Device:
      type: object
      properties:
        uuid:
          type: string
          readOnly: true
          example: 95494c38-72db-43b7-a523-d798616dc8d1
        alias:
          type: string
          example: Device 1
        canvasId:
          type: integer
          example: 1
    Devices:
      type: array
      items:
        $ref: '#/components/schemas/Device'
    Canvas:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: NOC
        owner:
          type: string
          example: admin
        carousel:
          type: array
          items:
            type: integer
          example: []
    Canvases:
      type: array
      items:
        $ref: '#/components/schemas/Canvas'
    WidgetPatchExample:
      type: object
      properties:
        conf:
          type: object
          properties:
            bladeId:
              type: string
              example: 8
            bladeAddr:
              type: string
              example: 10.0.30.188
            bladeName:
              type: string
              example: Extractor
            iface:
              type: string
              example: OTT
            streamName:
              type: string
              example: Stream02
            sid:
              type: integer
              example: 0
            pid:
              type: integer
              example: -1
            serviceName:
              type: string
              example: Unknown
            url:
              type: string
              example: /extractor/static/images/thums/ott_2_0.jpg
    Widget:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 1
        name:
          type: string
          example: thumb
        conf:
          type: object
          properties:
            width:
              type: integer
              example: 450
            height:
              type: integer
              example: 255
            top:
              type: integer
              example: 0
            left:
              type: integer
              example: 0
            bladeId:
              type: string
              example: 8
            bladeAddr:
              type: string
              example: 10.0.30.188
            bladeName:
              type: string
              example: Extractor
            iface:
              type: string
              example: OTT
            streamName:
              type: string
              example: Stream01
            sid:
              type: integer
              example: 0
            pid:
              type: integer
              example: -1
            serviceName:
              type: string
              example: Unknown
            plaqueDisplay:
              type: string
              example: Top
            plaqueText:
              type: string
              example: Stream01 via Extractor (OTT)
            url:
              type: string
              example: /extractor/static/images/thums/ott_9_0.jpg
          additionalProperties: true
        serial:
          type: integer
          example: 2
    Widgets:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Widget'