swagger.yaml

swagger: "2.0"
info:
  title: "dp-cantabular-metadata-extractor-api"
  description: "Supply Cantabular metadata (2021) for Florence metadata journey."
  version: 1.0.0
  license:
    name: "Open Government Licence v3.0"
    url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
basePath: "/v1"
schemes:
  - http
tags:
  - name: "public"
paths:

  /cantabular-metadata/dataset/{dataset}/lang/{lang}:
    get:
      parameters:
      - name: dataset
        type: string
        in: path
        required: true
        description: "The name of the dataset table (aka cantabular blob), used by the cantabular metadata service, such as RM001."
      - name: lang
        type: string
        in: path
        required: true
        description: "The abbreviation that refers to the language. Currently the only one accepted is en."
      tags:
        - public
      summary: 2021 Metadata Endpoint
      description: Returns all available 2021 Metadata.
      produces:
        - application/json
      responses:
        200:
          description: "Successfully returned metadata, for the requested dataset and language."
        500:
          $ref: '#/responses/InternalError'

  /health:
    get:
      tags:
        - public
      summary: "Returns API's health status"
      description: "Returns health status of the API and checks on dependent services"
      produces:
        - application/json
      responses:
        200:
          description: "Successfully returns OK status with checks of dependent services"
          schema:
            $ref: "#/definitions/Health"
        429:
          description: "Services warming up or degraded (at least one check in WARNING or CRITICAL status)"
        500:
          $ref: "#/responses/InternalError"

responses:
  InternalError:
    description: "Failed to process the request due to an internal error"

definitions:
  Health:
    type: object
    properties:
      status:
        type: string
        description: "The status of the API"
        enum: ["OK", "WARNING", "CRITICAL"]
      version:
        type: object
        properties:
          build_time:
            type: string
            description: "The build date and time of the API"
            example: "2020-06-11T12:49:20+01:00"
          git_commit:
            type: string
            description: "The git commit hash of the API"
            example: "7c2febbf2b818175112478d4ffbadbee1b654f63"
          language:
            type: string
            description: "The programming language used to implement API"
            example: "go"
          language_version:
            type: string
            description: "The version of the programming language used to implement API"
            example: "go1.14.3"
          version:
            type: string
            description: "The version of API"
            example: "1.0.0"
      uptime:
        type: string
        description: "The uptime of API"
        example: "34516"
      start_time:
        type: string
        description: "The start date and time of API running"
        example: "2020-06-11T11:49:21.520922Z"
      checks:
        type: array
        items:
          $ref: '#/definitions/HealthChecker'
  HealthChecker:
    type: object
    properties:
      name:
        type: string
        description: "The name of service used by API"
        enum: ["dp-cantabular-metadata-service"]
      status:
        type: string
        description: "The status of the service"
        enum: ["OK", "WARNING", "CRITICAL"]
      message:
        type: string
        description: "The message status of the service"
        example: "dp-cantabular-metadata-service is ok"
      last_checked:
        type: string
        description: "The last health check date and time of the service"
        example: "2020-06-11T11:49:50.330089Z"
      last_success:
        type: string
        description: "The last successful health check date and time of the service"
        example: "2020-06-11T11:49:50.330089Z"
      last_failure:
        type: string
        description: "The last failed health check date and time of the service"
        example: "2019-09-22T11:48:51.0000001Z"