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: 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/PlayLog'
                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/PlayLog'
        "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: Schedule info for clock
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClockInfo'
        "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/since/{date_time}:
    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: date_time
        in: path
        description: Get entries after this timestamp (e.g. '2020-08-29T09:12:33.001Z')
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - 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:
          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
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
          example: 2
      example:
        track_album: '...And the Circus Leaves Town'
        track_start: 2020-08-29T09:12:33.001Z
        track_title: El Rodeo
        track_artist: Kyuss
        track_duration: 303
        track_type: 2
    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
          example: 2
        timeslot_id:
          type: integer
          example: 1
        show_name:
          type: string
          example: Electronic Music from Brazil
        log_source:
          type: integer
          example: 1
      example:
        track_album: Bricolage
        track_start: 2020-08-29T09:12:33.001Z
        track_title: Chomp Samba
        show_name: Electronic Music from Brazil
        log_source: 1
        track_artist: Amon Tobin
        timeslot_id: 1
        track_duration: 808
        track_type: 2
    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:
      required:
      - current_timeslot
      type: object
      properties:
        current_track:
          $ref: '#/components/schemas/PlayLog'
        current_timeslot:
          $ref: '#/components/schemas/Timeslot'
        next_timeslot:
          $ref: '#/components/schemas/Timeslot'
      example:
        current_timeslot:
          timeslot_end: 2020-08-29T09:12:33.001Z
          playlist_id: 38
          show_name: Future Pop
          fallback_type: 0
          timeslot_start: 2020-08-29T09:12:33.001Z
          timeslot_id: 42
          schedule_id: 23
          tracks:
          - track_album: '...And the Circus Leaves Town'
            track_start: 2020-08-29T09:12:33.001Z
            track_title: El Rodeo
            track_artist: Kyuss
            track_duration: 303
            track_type: 2
          - track_album: '...And the Circus Leaves Town'
            track_start: 2020-08-29T09:12:33.001Z
            track_title: El Rodeo
            track_artist: Kyuss
            track_duration: 303
            track_type: 2
        current_track:
          track_album: Bricolage
          track_start: 2020-08-29T09:12:33.001Z
          track_title: Chomp Samba
          show_name: Electronic Music from Brazil
          log_source: 1
          track_artist: Amon Tobin
          timeslot_id: 1
          track_duration: 808
          track_type: 2
    Timeslot:
      required:
      - show_name
      - timeslot_end
      - timeslot_start
      - tracks
      type: object
      properties:
        show_name:
          type: string
          example: Future Pop
        schedule_id:
          type: integer
          example: 23
        timeslot_id:
          type: integer
          example: 42
        timeslot_start:
          type: string
          format: date-time
          example: 2020-08-29T09:12:33.001Z
        timeslot_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
        tracks:
          type: array
          items:
            $ref: '#/components/schemas/Track'
      example:
        timeslot_end: 2020-08-29T09:12:33.001Z
        playlist_id: 38
        show_name: Future Pop
        fallback_type: 0
        timeslot_start: 2020-08-29T09:12:33.001Z
        timeslot_id: 42
        schedule_id: 23
        tracks:
        - track_album: '...And the Circus Leaves Town'
          track_start: 2020-08-29T09:12:33.001Z
          track_title: El Rodeo
          track_artist: Kyuss
          track_duration: 303
          track_type: 2
        - track_album: '...And the Circus Leaves Town'
          track_start: 2020-08-29T09:12:33.001Z
          track_title: El Rodeo
          track_artist: Kyuss
          track_duration: 303
          track_type: 2
    inline_response_400:
      type: object
      properties:
        message:
          type: string

