swagger: "2.0"

info:
  version: 1.0.0
  title: API Specifications

schemes:
  - https
host: qa-ows-charts.theorchard.io
paths:
  /:
    get:
      summary: Hello World path.
      responses:
        200:
          description: 200 OK
          examples:
            text/html: "Hello Bill!"
  /{username}:
    get:
      summary: Hello World with an optional GET param "username".
      parameters:
        - in: path
          name: username
          required: true
          type: string
      responses:
        200:
          description: 200 OK
          examples:
            text/html: "Hello Bill!"
  /hello/:
    get:
      summary: Check the health of the application.
      responses:
        200:
          description: 200 OK
          examples:
            application/json: { "status": "ok" }

  /new-music-friday/dates:
    get:
      summary: List the available New Music Friday chart dates.
      tags: [New Music Friday]
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/NewMusicFridayDatesResponse'

  /new-music-friday/{date}/markets/:
    get:
      summary: List the markets tracked for a given New Music Friday date and whether their data has been received.
      tags: [New Music Friday]
      parameters:
        - in: path
          name: date
          required: true
          type: string
          description: Chart date in YYYY-MM-DD format.
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/NewMusicFridayDateMarketsResponse'

  /new-music-friday/{date}/entries/:
    get:
      summary: List New Music Friday entries for a given date.
      tags: [New Music Friday]
      parameters:
        - in: path
          name: date
          required: true
          type: string
          description: Chart date in YYYY-MM-DD format.
        - in: query
          name: filter
          required: false
          type: string
          default: "{}"
          description: JSON-encoded filter object.
        - in: query
          name: order
          required: false
          type: string
          default: '[{"by":"FEATURING","dir":"DESC"},{"by":"TOP_10_RANK","dir":"DESC"},{"by":"AVERAGE_POSITION","dir":"ASC"}]'
          description: JSON-encoded list of order clauses.
        - in: query
          name: offset
          required: false
          type: integer
          default: 0
        - in: query
          name: limit
          required: false
          type: integer
          default: 200
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/NewMusicFridayDateEntriesResponse'

  /new-music-friday/{date}/search/:
    get:
      summary: Cortex-backed track/artist/ISRC search across New Music Friday entries for a given date.
      tags: [New Music Friday]
      parameters:
        - in: path
          name: date
          required: true
          type: string
          description: Chart date in YYYY-MM-DD format.
        - in: query
          name: term
          required: true
          type: string
          description: Search term — track name, artist name, or an ISRC.
      responses:
        200:
          description: 200 OK
          schema:
            $ref: '#/definitions/NewMusicFridayDateEntriesResponse'

definitions:
  NewMusicFridayDatesResponse:
    type: object
    required: [dates]
    properties:
      dates:
        type: array
        items:
          type: string
          description: Chart date in YYYY-MM-DD format.

  NewMusicFridayDateMarketsResponse:
    type: object
    required: [markets]
    properties:
      markets:
        type: array
        items:
          $ref: '#/definitions/NewMusicFridayDateMarket'

  NewMusicFridayDateMarket:
    type: object
    required: [market, data_received]
    properties:
      market:
        type: string
      data_received:
        type: boolean

  NewMusicFridayDateEntriesResponse:
    type: object
    required: [total, entries]
    properties:
      total:
        type: integer
      entries:
        type: array
        items:
          $ref: '#/definitions/NewMusicFridayDateEntry'

  NewMusicFridayDateEntry:
    type: object
    required:
      - isrc
      - track_name
      - artist_name
      - image_url
      - feature
      - average_position
      - top_10_rank
      - placements
    properties:
      isrc:
        type: string
      track_name:
        type: string
        x-nullable: true
        description: May be null when Spotify track metadata has not yet been ingested for this ISRC.
      artist_name:
        type: string
        x-nullable: true
        description: May be null when Spotify track metadata has not yet been ingested for this ISRC.
      image_url:
        type: string
        x-nullable: true
        description: May be null when Spotify track metadata has not yet been ingested for this ISRC.
      feature:
        type: integer
        description: Number of NMF markets in which this ISRC has a charting position on the date.
      average_position:
        type: number
        format: float
        x-nullable: true
        description: >-
          Average chart position across all NMF markets where this entry charts on the date.
          Null when the ISRC has no charting positions in any market with data_received=true on the
          requested date (e.g. an ISRC matched by search whose only chart appearances are in markets
          whose data has not yet been received).
      top_10_rank:
        type: integer
        description: Number of NMF markets in which this ISRC charts in the top 10.
      placements:
        type: array
        items:
          $ref: '#/definitions/NewMusicFridayPlacement'

  NewMusicFridayPlacement:
    type: object
    required: [market, position, spotify_id]
    properties:
      market:
        type: string
      position:
        type: integer
        x-nullable: true
      spotify_id:
        type: string