engine.yaml

openapi: 3.0.0
info:
  title: AURA Engine API
  description: This is the AURA Engine API. Read more at https://gitlab.servus.at/aura/engine.
  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
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
tags:
- name: public
  description: Operations available to the public
- name: internal
  description: Secured, internal 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.controllers.public_controller
  /trackservice/{trackId}:
    get:
      tags:
      - public
      summary: Get a single track by ID
      description: |
        Retrieves a single track by its ID.
      operationId: get_track
      parameters:
      - name: trackId
        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.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.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.controllers.internal_controller
  /status/active:
    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.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: One Small Step
        track_duration:
          type: integer
          example: 234
        track_type:
          type: string
          example: Live
        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: Experimental
        show_topic:
          type: string
          example: Music
      example:
        track_album: Bricolage
        show_funding_category: Standard
        show_id: 1
        schedule_fallback_type: 0
        track_title: One Small Step
        show_name: Special Music Show
        track_artist: Amon Tobin
        show_topic: Music
        track_type: Live
        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: Experimental
        schedule_id: 1
        schedule_start: 2020-08-29T09:12:33.001Z
    StatusEntry:
      required:
      - engine_host
      - health_info
      - is_active
      - is_healthy
      - log_time
      type: object
      properties:
        log_time:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        engine_host:
          type: string
          example: engine1.local
        is_healthy:
          type: boolean
          example: true
        is_active:
          type: boolean
          example: true
        health_info:
          type: string
          example: '{}'
      example:
        is_healthy: true
        is_active: true
        health_info: '{}'
        engine_host: engine1.local
        log_time: 2020-08-29T09:12:33.001Z