openapi: 3.0.0
info:
  title: AURA Engine API
  description: This is the AURA Engine API.
  contact:
    email: david.trattnig@subsquare.at
  license:
    name: AGPL 3.0
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  version: 1.0.0
externalDocs:
  description: Find more info here
  url: https://gitlab.servus.at/aura/engine-api
servers:
- url: '{protocol}://{api-host}:{port}/api/{version}'
  description: Engine API
  variables:
    protocol:
      default: http
      enum:
      - http
      - https
    api-host:
      description: Hostname or IP for API Host
      default: localhost
    port:
      default: "8008"
    version:
      default: v1
- url: https://virtserver.swaggerhub.com/AURA-Engine/engine-api/1.0.0
  description: SwaggerHub API Auto Mocking
tags:
- name: public
  description: Operations available to the public
- name: internal
  description: Secured calls only
paths:
  /trackservice:
    get:
      tags:
      - public
      summary: List recent tracks in the play-log
      description: |
        Lists the track-service entries for a given page.
      operationId: list_tracks
      parameters:
      - name: from_date
        in: query
        description: Get entries after this timestamp
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
        example: 2020-08-29T09:12:33.001Z
      - name: to_date
        in: query
        description: Get entries before this timestamp
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
        example: 2020-11-29T09:12:55.001Z
      - name: page
        in: query
        description: The number of items to skip before starting to collect the result
          set
        required: false
        style: form
        explode: true
        schema:
          type: integer
      - name: limit
        in: query
        description: The numbers of items to return per page
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 1
          type: integer
          default: 20
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Track'
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.public_controller
  /trackservice/current:
    get:
      tags:
      - public
      summary: Get current track
      description: |
        Retrieves the currently playing track.
      operationId: current_track
      responses:
        "200":
          description: Track currently playing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Track'
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.public_controller
  /clock:
    get:
      tags:
      - internal
      summary: Get all information to display the studio clock
      description: |
        Retrieves the currently playing schedule, its playlist and entries plus the next schedule for being used by the studio clock.
      operationId: clock_info
      responses:
        "200":
          description: Show, Schedule and Playlist info for the Studio Clock
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClockInfo'
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
    put:
      tags:
      - internal
      summary: Set current studio clock information such as schedule info and track-list
        for engine 1 or 2
      description: |
        Set current studio clock information (source, schedule and track-list) and the next schedule of the given play-out source (engine1, engine2). Please note, the `current_track` information is ignored in the PUT request. It's only populated in the GET request. To store current track information use `/playlog/store` instead.
      operationId: set_clock_info
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClockInfo'
        required: true
      responses:
        "200":
          description: status updated
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
  /playlog/store:
    post:
      tags:
      - internal
      summary: Adds an entry to the playlog
      description: |
        Stores the passed playlog entry
      operationId: add_playlog
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlayLog'
        required: true
      responses:
        "200":
          description: Successfully created a new playlog
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
      x-openapi-router-controller: src.rest.controllers.internal_controller
  /playlog:
    get:
      tags:
      - internal
      summary: List tracks in the play-log since the given timestamp
      description: |
        Get paginated playlog entries for since the given timestamp.
      operationId: list_playlog
      parameters:
      - name: from_date
        in: query
        description: Get entries after this timestamp
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
        example: 2020-08-29T09:12:33.001Z
      - name: to_date
        in: query
        description: Get entries before this timestamp
        required: false
        style: form
        explode: true
        schema:
          type: string
          format: date-time
        example: 2020-11-29T09:12:55.001Z
      - name: page
        in: query
        description: The number of items to skip before starting to collect the result
          set
        required: false
        style: form
        explode: true
        schema:
          type: integer
      - name: limit
        in: query
        description: The numbers of items to return per page
        required: false
        style: form
        explode: true
        schema:
          maximum: 200
          minimum: 1
          type: integer
          default: 50
      - name: skip_synced
        in: query
        description: If true only returns items which are in unsynced state on the
          main node
        required: false
        style: form
        explode: true
        schema:
          type: boolean
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlayLog'
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
  /playlog/report/{year_month}:
    get:
      tags:
      - internal
      summary: Report for one month
      description: |
        Returns a report for the given month
      operationId: get_report
      parameters:
      - name: year_month
        in: path
        description: Month to create the report for in the format "yyyy_mm"
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        "200":
          description: report matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlayLog'
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
  /source/active:
    get:
      tags:
      - internal
      summary: Get active play-out source (engine1, engine2)
      description: |
        Retrieves the status entry of the currently active source (engine 1, 2 or other source)
      operationId: get_active_source
      responses:
        "200":
          description: source number
          content:
            application/json:
              schema:
                type: integer
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
  /source/active/{number}:
    put:
      tags:
      - internal
      summary: Set active play-out source (engine1, engine2)
      description: |
        Activates one engine and deactivates the other
      operationId: set_active_source
      parameters:
      - name: number
        in: path
        description: Number of the engine
        required: true
        style: simple
        explode: false
        schema:
          maximum: 2
          minimum: 1
          type: integer
      responses:
        "200":
          description: status updated
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
  /source/health/{number}:
    get:
      tags:
      - internal
      summary: Get most recent health info
      description: |
        Retrieves the most recent health info of the requested engine
      operationId: get_source_health
      parameters:
      - name: number
        in: path
        description: Number of the engine
        required: true
        style: simple
        explode: false
        schema:
          maximum: 2
          minimum: 1
          type: integer
      responses:
        "200":
          description: report matching criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthLog'
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
    post:
      tags:
      - internal
      summary: Log health info
      description: |
        Logs another health entry for the given engine
      operationId: log_source_health
      parameters:
      - name: number
        in: path
        description: Number of the engine
        required: true
        style: simple
        explode: false
        schema:
          minimum: 1
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HealthLog'
        required: true
      responses:
        "200":
          description: health info logged
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
components:
  schemas:
    Track:
      required:
      - track_start
      type: object
      properties:
        track_start:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        track_artist:
          type: string
          example: Kyuss
        track_album:
          type: string
          example: '... And the Circus Leaves Town'
        track_title:
          type: string
          example: El Rodeo
        track_duration:
          type: integer
          example: 303
        track_type:
          type: integer
          description: 'Indicates the type: "0" = filesystem, "1" = stream, "2" =
            live or line in'
          example: 2
        track_num:
          type: integer
          example: 11
        playlist_id:
          type: integer
          example: 38
        schedule_id:
          type: integer
          example: 23
        show_id:
          type: integer
          example: 42
        show_name:
          type: string
          example: Electronic Music from Brazil
      example:
        track_album: '... And the Circus Leaves Town'
        show_id: 42
        playlist_id: 38
        track_start: 2020-08-29T09:12:33.001Z
        track_title: El Rodeo
        track_num: 11
        show_name: Electronic Music from Brazil
        track_artist: Kyuss
        track_duration: 303
        track_type: 2
        schedule_id: 23
    PlayLog:
      required:
      - track_start
      type: object
      properties:
        track_start:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        track_artist:
          type: string
          example: Amon Tobin
        track_album:
          type: string
          example: Bricolage
        track_title:
          type: string
          example: Chomp Samba
        track_duration:
          type: integer
          example: 808
        track_type:
          type: integer
          description: 'Indicates the type: "0" = filesystem, "1" = stream, "2" =
            live or line in'
          example: 2
        track_num:
          type: integer
          example: 11
        playlist_id:
          type: integer
          example: 38
        schedule_id:
          type: integer
          example: 23
        show_id:
          type: integer
          example: 42
        show_name:
          type: string
          example: Electronic Music from Brazil
        log_source:
          type: integer
          description: From which engine the entry has been logged from e.g. "1" for
            Engine 1 or "2" for Engine 2
          example: 1
        is_synced:
          type: boolean
          description: For Engine API internal use only - On a main node such as Engine
            1 or 2 this flag indicates if the playlog has been actively synced to
            the sync node. On the sync node in contrast this flag indicates if the
            playlog has been passively synced from one of the main nodes.
          example: true
      example:
        track_album: Bricolage
        show_id: 42
        track_title: Chomp Samba
        show_name: Electronic Music from Brazil
        track_artist: Amon Tobin
        track_type: 2
        is_synced: true
        playlist_id: 38
        track_start: 2020-08-29T09:12:33.001Z
        track_num: 11
        log_source: 1
        track_duration: 808
        schedule_id: 23
    HealthLog:
      required:
      - details
      - is_healthy
      - log_time
      type: object
      properties:
        log_time:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        is_healthy:
          type: boolean
          example: true
        details:
          type: string
          example: Stringified JSON Object
      example:
        is_healthy: true
        details: Stringified JSON Object
        log_time: 2020-08-29T09:12:33.001Z
    ClockInfo:
      type: object
      properties:
        engine_source:
          type: integer
          example: 1
        current_track:
          $ref: '#/components/schemas/PlayLog'
        current_playlist:
          $ref: '#/components/schemas/Playlist'
        current_schedule:
          $ref: '#/components/schemas/Schedule'
        next_schedule:
          $ref: '#/components/schemas/Schedule'
      example:
        engine_source: 1
        current_playlist:
          entries:
          - track_album: Bricolage
            track_start: 2020-08-29T09:12:33.001Z
            track_title: Chomp Samba
            track_num: 7
            track_artist: Amon Tobin
            track_duration: 808
            track_type: 2
          - track_album: Bricolage
            track_start: 2020-08-29T09:12:33.001Z
            track_title: Chomp Samba
            track_num: 7
            track_artist: Amon Tobin
            track_duration: 808
            track_type: 2
          playlist_id: 38
        current_track:
          track_album: Bricolage
          show_id: 42
          track_title: Chomp Samba
          show_name: Electronic Music from Brazil
          track_artist: Amon Tobin
          track_type: 2
          is_synced: true
          playlist_id: 38
          track_start: 2020-08-29T09:12:33.001Z
          track_num: 11
          log_source: 1
          track_duration: 808
          schedule_id: 23
        current_schedule:
          show_id: 42
          playlist_id: 38
          show_name: Electronic Music from Brazil
          fallback_type: 0
          schedule_end: 2020-08-29T09:12:33.001Z
          schedule_id: 23
          schedule_start: 2020-08-29T09:12:33.001Z
        next_schedule: null
    Schedule:
      required:
      - schedule_end
      - schedule_start
      - show_name
      type: object
      properties:
        show_name:
          type: string
          example: Electronic Music from Brazil
        show_id:
          type: integer
          example: 42
        schedule_id:
          type: integer
          example: 23
        schedule_start:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        schedule_end:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        playlist_id:
          type: integer
          example: 38
        fallback_type:
          type: integer
          example: 0
      example:
        show_id: 42
        playlist_id: 38
        show_name: Electronic Music from Brazil
        fallback_type: 0
        schedule_end: 2020-08-29T09:12:33.001Z
        schedule_id: 23
        schedule_start: 2020-08-29T09:12:33.001Z
    Playlist:
      required:
      - entries
      type: object
      properties:
        playlist_id:
          type: integer
          example: 38
        entries:
          type: array
          items:
            $ref: '#/components/schemas/PlaylistEntry'
      example:
        entries:
        - track_album: Bricolage
          track_start: 2020-08-29T09:12:33.001Z
          track_title: Chomp Samba
          track_num: 7
          track_artist: Amon Tobin
          track_duration: 808
          track_type: 2
        - track_album: Bricolage
          track_start: 2020-08-29T09:12:33.001Z
          track_title: Chomp Samba
          track_num: 7
          track_artist: Amon Tobin
          track_duration: 808
          track_type: 2
        playlist_id: 38
    PlaylistEntry:
      required:
      - track_start
      type: object
      properties:
        track_start:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        track_artist:
          type: string
          example: Amon Tobin
        track_album:
          type: string
          example: Bricolage
        track_title:
          type: string
          example: Chomp Samba
        track_duration:
          type: integer
          example: 808
        track_type:
          type: integer
          example: 2
        track_num:
          type: integer
          example: 7
      example:
        track_album: Bricolage
        track_start: 2020-08-29T09:12:33.001Z
        track_title: Chomp Samba
        track_num: 7
        track_artist: Amon Tobin
        track_duration: 808
        track_type: 2
    inline_response_400:
      type: object
      properties:
        message:
          type: string

