swagger.yml

swagger: "2.0"
info:
  title: ACRCloud Webhooks Receiver
  description: |
    Hooks to receive ACRCloud events on and a simple API to query the received data.
    Stores all data in a PostgreSQL database for later querying.
  version: 0.1.0
  license:
    name: "AGPLv3"
    url: "https://www.gnu.org/licenses/agpl-3.0.en.html"
schemes:
- "https"
- "http"
consumes:
- "application/json"
produces:
- "application/json"
tags:
- name: webhook
  description: Webhooks called by ACRCloud.
- name: api
  description: API to interact with the stored data.
- name: compat
  description: Compatibility endpoints that match the ACRCloud API.
paths:
  /v1/_webhooks/results:
    post:
      summary: "ACRCloud results callback"
      description: "This hook is called by the ACRCloud service when it knows what song we weere playing."
      operationId: "addResult"
      tags:
      - "webhook"
      security:
      - api_key: []
      parameters:
      - $ref: '#/parameters/requestID'
      - in: "body"
        name: "body"
        description: "ACRCloud results entry"
        required: true
        schema:
          $ref: "#/definitions/Webhook"
      responses:
        "201":
          description: "Created"
        "400":
          description: "Bad Request"
        "500":
          description: "Server Error"
  /v1/results:
    get:
      summary: "Get ACRCloud Results"
      description: "This is endpoint is useful for looking into and exporting the dataset."
      operationId: "getResults"
      tags:
      - "api"
      parameters:
        - $ref: '#/parameters/requestID'
        - $ref: '#/parameters/offsetParam'
        - $ref: '#/parameters/limitParam'
        - in: query
          name: from
          required: false
          type: string
          format: date-time
        - in: query
          name: to
          required: false
          type: string
          format: date-time
      responses:
        "200":
          description: "Returns array of results"
          schema:
            type: array
            items:
              $ref: '#/definitions/Result'
        "500":
          description: "Server Error"
  /v1/results/{resultId}:
    get:
      summary: "ACRCloud result"
      description: "Use this endpoint to fetch information on an exact entry."
      operationId: "getResult"
      tags:
      - "api"
      parameters:
      - $ref: '#/parameters/requestID'
      - in: path
        name: resultId
        required: true
        type: integer
      responses:
        "200":
          description: "Returns single result"
          schema:
            $ref: '#/definitions/Result'
        "500":
          description: "Server Error"
  /v1/monitor-streams/{streamId}/results:
    get:
      summary: "ACRCloud Custom Streams Full Day Endpoint"
      description: "This endpoint implements the same API as upstream ACRCloud does."
      operationId: "getCustomStream"
      tags:
      - "compat"
      parameters:
      - $ref: '#/parameters/requestID'
      - in: path
        name: streamId
        description: Stream ID, default is the non-realtime RaBe program.
        required: true
        type: string
        default: s-qXuJARB
      - in: query
        name: access_key
        description: Ignored but available for compatibility with upstream.
        required: false
        type: string
      - in: query
        name: date
        description: The UTC date in the format 'YYYYMMDD'
        required: true
        type: string
      responses:
        "200":
          description: "Results without local ID"
          schema:
            type: array
            items:
              $ref: '#/definitions/Data'
        "400":
          description: "Bad Request"
        "500":
          description: "Server Error"
securityDefinitions:
  api_key:
    type: "apiKey"
    name: "api_key"
    description: Used to secure the Webhook endpoints.
    in: query
parameters:
  offsetParam:
    in: query
    name: offset
    required: false
    type: integer
    minimum: 0
    default: 0
    description: The number of items to skip before starting to collect the result set.
  limitParam:
    in: query
    name: limit
    required: false
    type: integer
    minimum: 1
    default: 20
    description: The numbers of items to return.
  requestID:
    in: header
    name: X-Request-ID
    type: string
definitions:
  Result:
    type: "object"
    properties:
      ID:
        type: "integer"
        x-go-custom-tag: gorm:"primaryKey;"
      result:
        $ref: '#/definitions/Webhook'
        x-go-custom-tag: gorm:"type:jsonb;"
      timestamp:
        type: "string"
        format: "date-time"
        x-go-custom-tag: gorm:"type:time;index;"
  Webhook:
    type: "object"
    properties:
      stream_id:
        type: "string"
      stream_url:
        type: "string"
      status:
        type: "integer"
        format: "int32"
      data:
        $ref: '#/definitions/Data'
    required:
      - stream_id
      - stream_url
      - status
      - data
  Data:
    type: "object"
    properties:
      status:
        $ref: '#/definitions/Status'
        x-go-custom-tag: gorm:"type:jsonb;"
      result_type:
        type: integer
        format: int32
      metadata:
        $ref: '#/definitions/Metadata'
        x-go-custom-tag: gorm:"type:jsonb;"
    required:
      - status
      - metadata
  Status:
    type: object
    properties:
      msg:
        type: string
      version:
        type: string
      code:
        type: integer
        format: int32
    required:
      - msg
      - version
      - code
  Metadata:
    type: object
    properties:
      music:
        type: array
        items:
          $ref: '#/definitions/Music'
      timestamp_utc:
        type: string
      played_duration:
        type: integer
        format: int64
    required:
      - timestamp_utc
      - played_duration
  Music:
    type: object
    properties:
      acrid:
        type: string
      result_from:
        type: integer
        format: int32
      score:
        type: integer
        minimum: 0
        maximum: 100
      title:
        type: string
      artists:
        type: array
        items:
          $ref: '#/definitions/Artist'
      album:
        $ref: '#/definitions/Album'
      genres:
        type: array
        items:
          $ref: '#/definitions/Genre'
      contributors:
        $ref: '#/definitions/Contributors'
      label:
        type: string
      release_date:
        type: string
      release_by_territories:
        type: array
        items:
          $ref: '#/definitions/Territory'
      rights_claim:
        type: array
        items:
          $ref: '#/definitions/RightsClaim'
      lyrics:
        $ref: '#/definitions/Lyrics'
      play_offset_ms:
        type: integer
        format: int64
      duration_ms:
        type: integer
        format: int64
      sample_begin_time_offset_ms:
        type: integer
        format: int64
      sample_end_time_offset_ms:
        type: integer
        format: int64
      db_begin_time_offset_ms:
        type: integer
        format: int64
      external_ids:
        $ref: '#/definitions/ExternalIds'
      external_metadata:
        $ref: '#/definitions/ExternalMetadata'
    required:
      - acrid
      - result_from
      - score
      - title
      - play_offset_ms
      - duration_ms
      - sample_begin_time_offset_ms
      - sample_end_time_offset_ms
      - db_begin_time_offset_ms
      - external_ids
      - external_metadata
  Album:
    type: object
    properties:
      name:
        type: string
    required:
      - name
  Artist:
    type: object
    properties:
      name:
        type: string
      roles:
        type: array
        items:
          type: string
    required:
      - name
  Contributors:
    type: object
    properties:
      composers:
        type: array
        items:
          type: string
      lyricists:
        type: array
        items:
          type: string
  Genre:
    type: object
    properties:
      name:
        type: string
  Lyrics:
    type: object
    properties:
      copyrights:
        type: array
        items:
          type: string
  Territory:
    type: object
    properties:
      territories:
        type: array
        items:
          type: string
      release_date:
        type: string
  RightsClaim:
    type: object
    properties:
      distributor:
        $ref: '#/definitions/Distributor'
      territories:
        type: array
        items:
          type: string
      start_date:
        type: string
      rights_claim_policy:
        type: string
      rights_owners:
        type: array
        items:
          $ref: '#/definitions/RightsOwner'
  Distributor:
    type: object
    properties:
      name:
        type: string
      id:
        type: string
  RightsOwner:
    type: object
    properties:
      share_percentage:
        type: integer
      name:
        type: string
  ExternalIds:
    type: object
    properties:
      deezer:
        type: string
      isrc: {}
        # ISRC can be either a string or an array of string because they
        # are just weird like that. In swagger 3.0 we would configure
        # this so it allows both. With swagger 2.0 all can do is ignore
        # validation on the property completely.
        # type: string
      itunes:
        type: string
      lyricfind:
        type: string
      musicstory:
        type: string
      spotify:
        type: string
      upc: {}
        # Depending on how a thing was released it can also have more
        # than one UPC assigned. This seems to only affect cases where
        # a recording has been assigned multiple ISRC numbers. Given
        # this chaos stems from the collection societies it really
        # doesn't look like have that much interest in receiving
        # complete reports. This kind of adds up with the fact that
        # broadcasters get a rebate for complete listings.
        # Fuck capitalism!
        # type: string
      youtube:
        type: string
  ExternalMetadata:
    type: object
    properties:
      deezer:
        type: object
      isrc:
        type: object
      itunes:
        type: object
      lyricfind:
        type: object
      musicstory:
        type: object
      spotify:
        type: object
      upc:
        type: object
      youtube:
        type: object
externalDocs:
  description: "Find out more about Radio Bern RaBe"
  url: "https://rabe.ch"