thamanyah/discovery/docs/swagger.yaml

basePath: /
definitions:
  api.HealthResponse:
    properties:
      status:
        example: ok
        type: string
    type: object
  api.ProblemDetails:
    properties:
      detail:
        example: The catalogue could not be read from the database. This is a server-side
          fault and the request was not processed; retrying in a few moments may succeed.
        type: string
      status:
        example: 500
        type: integer
      title:
        example: Something Went Wrong Loading The Catalogue
        type: string
      type:
        example: about:blank
        type: string
    type: object
  api.SearchResults:
    properties:
      nextCursor:
        description: |-
          NextCursor reaches the page after this one. Empty on the last page,
          which is how a reader knows there is no more to ask for.
        type: string
      videos:
        description: |-
          Videos are the matches, most relevant first. Never null: a search that
          matches nothing is an empty list.
        items:
          $ref: '#/definitions/api.Video'
        type: array
    type: object
  api.Video:
    properties:
      categories:
        example:
        - documentary
        - news
        items:
          type: string
        type: array
      id:
        example: 0f8fad5b-d9cb-469f-a165-70867728950e
        type: string
      playbackUrl:
        example: https://d111111abcdef8.cloudfront.net/videos/abc123/index.m3u8
        type: string
      title:
        example: The Evening Bulletin
        type: string
    type: object
info:
  contact: {}
  description: |-
    JSON API for browsing the Thamanyah catalogue. Read-side counterpart to the CMS, which is what ingests videos.

    The catalogue search is `GET /api/videos`, listed below: title is matched lexically with the last word as a prefix, categories narrow to videos filed under any one of them, limit defaults to 20 and is capped at 100, and cursor is the opaque `nextCursor` of a previous search.
  title: Thamanyah Discovery API
  version: "1.0"
paths:
  /api/videos:
    get:
      description: Finds catalogued videos by the words of their title and the categories
        they are filed under, most relevant first. Every parameter is optional — a
        request with none of them browses the whole catalogue, newest first. Paging
        is by cursor rather than by offset, so a page stays the same page while videos
        are being announced into the catalogue around it.
      parameters:
      - description: 'Matched lexically against video titles: the words are all required,
          and the last is treated as a prefix so a part-typed word still finds something.'
        example: desert fal
        in: query
        name: title
        type: string
      - collectionFormat: multi
        description: Narrows the search to videos filed under any one of these names
          — not all of them. Repeat the parameter per category. Omitted means every
          category.
        example: documentary
        in: query
        items:
          type: string
        name: categories
        type: array
      - default: 20
        description: How many videos to return. Absent, zero or negative takes the
          default of 20; anything above the maximum of 100 is capped to it rather
          than refused, and the cursor still reaches the rest.
        in: query
        name: limit
        type: integer
      - description: Asks for the page after the one a previous search ended at. Send
          back the nextCursor from that search unchanged; it is opaque, and the only
          thing to do with it is return it.
        in: query
        name: cursor
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/api.SearchResults'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ProblemDetails'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ProblemDetails'
      summary: Search the catalogue
      tags:
      - videos
  /api/videos/{id}:
    get:
      description: 'Returns the catalogue''s copy of a video: what a reader needs
        to show and play it. A video appears here only after the CMS has announced
        it as ready, so a video that is still transcoding — or one the CMS never made
        ready — is a 404.'
      parameters:
      - description: Video id, as issued by the CMS
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/api.Video'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/api.ProblemDetails'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ProblemDetails'
      summary: Get a catalogued video
      tags:
      - videos
  /health:
    get:
      description: Reports that the service is up and serving. Used as the ALB target
        group health check; it does not verify the database connection.
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/api.HealthResponse'
      summary: Health check
      tags:
      - system
swagger: "2.0"