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 most recent track-service entries.
      operationId: list_tracks
      parameters:
      - name: offset
        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
        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/PlayLogEntry'
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.public_controller
  /trackservice/{track_id}:
    get:
      tags:
      - public
      summary: Get a single track by ID
      description: |
        Retrieves a single track by its ID.
      operationId: get_track
      parameters:
      - name: track_id
        in: path
        description: ID of the track-service entry
        required: true
        style: simple
        explode: false
        schema:
          type: integer
      responses:
        "200":
          description: Track matching the given ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlayLogEntry'
        "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/PlayLogEntry'
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.public_controller
  /playlist/current:
    get:
      tags:
      - public
      summary: Get current playlist
      description: |
        Retrieves the currently playing playlist.
      operationId: current_playlist
      responses:
        "200":
          description: Playlist currently playing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.public_controller
  /playlist/next:
    get:
      tags:
      - public
      summary: Get next playlist
      description: |
        Retrieves the playlist playing next
      operationId: next_playlist
      responses:
        "200":
          description: Playlist playing next
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playlist'
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.public_controller
  /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/PlayLogEntry'
                x-content-type: application/json
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
  /engine/current:
    get:
      tags:
      - internal
      summary: Get active engine
      description: |
        Retrieves the status entry of the currently active engine
      operationId: get_active_engine
      responses:
        "200":
          description: report matching criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusEntry'
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
  /engine/{engine_number}/health:
    get:
      tags:
      - internal
      summary: Get most recent health info
      description: |
        Retrieves the most recent health info of the requested engine
      operationId: get_engine_health
      parameters:
      - name: engine_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/HealthInfo'
        "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_engine_health
      parameters:
      - name: engine_number
        in: path
        description: Number of the engine
        required: true
        style: simple
        explode: false
        schema:
          maximum: 2
          minimum: 1
          type: integer
      responses:
        "200":
          description: health info logged
        "400":
          description: bad input parameter
      x-openapi-router-controller: src.rest.controllers.internal_controller
  /engine/{engine_number}/activate:
    put:
      tags:
      - internal
      summary: Set active engine
      description: |
        Activates one engine and deactivates the other
      operationId: activate_engine
      parameters:
      - name: engine_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
components:
  schemas:
    PlayLogEntry:
      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: 234
        track_type:
          type: integer
          example: 2
        schedule_id:
          type: integer
          example: 1
        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
        schedule_repetition:
          type: boolean
          example: false
        schedule_playlist_id:
          type: integer
          example: 1
        schedule_fallback_type:
          type: integer
          example: 0
        show_id:
          type: integer
          example: 1
        show_name:
          type: string
          example: Special Music Show
        show_funding_category:
          type: string
          example: Standard
        show_type:
          type: string
          example: Feature
        show_category:
          type: string
          example: Progressive
        show_topic:
          type: string
          example: Music
      example:
        track_album: Bricolage
        show_funding_category: Standard
        show_id: 1
        schedule_fallback_type: 0
        track_title: Chomp Samba
        show_name: Special Music Show
        track_artist: Amon Tobin
        show_topic: Music
        track_type: 2
        schedule_playlist_id: 1
        show_type: Feature
        track_start: 2020-08-29T09:12:33.001Z
        schedule_repetition: false
        schedule_end: 2020-08-29T09:12:33.001Z
        track_duration: 234
        show_category: Progressive
        schedule_id: 1
        schedule_start: 2020-08-29T09:12:33.001Z
    StatusEntry:
      required:
      - engine_host
      - engine_number
      - is_active
      - is_healthy
      - log_time
      type: object
      properties:
        log_time:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        engine_number:
          maximum: 2
          minimum: 1
          type: integer
        engine_host:
          type: string
          example: engine1.local
        is_healthy:
          type: boolean
          example: true
        is_active:
          type: boolean
          example: true
      example:
        is_healthy: true
        is_active: true
        engine_number: 1
        engine_host: engine1.local
        log_time: 2020-08-29T09:12:33.001Z
    HealthInfo:
      required:
      - details
      - log_time
      type: object
      properties:
        log_time:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        details:
          type: string
          example: Stringified JSON Object
      example:
        details: Stringified JSON Object
        log_time: 2020-08-29T09:12:33.001Z
    Playlist:
      required:
      - entries
      - schedule_end
      - schedule_start
      - show_name
      type: object
      properties:
        show_name:
          type: string
          example: Future Pop
        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
        entries:
          type: array
          items:
            $ref: '#/components/schemas/PlaylistEntry'
      example:
        entries:
        - duration: 363
          artist: xxyyxx
          album: XXYYXX
          title: Alone
          type: 1
        - duration: 363
          artist: xxyyxx
          album: XXYYXX
          title: Alone
          type: 1
        playlist_id: 38
        show_name: Future Pop
        fallback_type: 0
        schedule_end: 2020-08-29T09:12:33.001Z
        schedule_id: 23
        schedule_start: 2020-08-29T09:12:33.001Z
    PlaylistEntry:
      required:
      - title
      type: object
      properties:
        artist:
          type: string
          example: xxyyxx
        album:
          type: string
          example: XXYYXX
        title:
          type: string
          example: Alone
        duration:
          type: integer
          example: 363
        type:
          type: integer
          example: 1
      example:
        duration: 363
        artist: xxyyxx
        album: XXYYXX
        title: Alone
        type: 1