swagger.yaml

swagger: "2.0"
basePath: /v1
info:
  title: "dp-nlp-category-api"
  description: "A Python microservice to wrap the Bonn package to match queries on the ONS Website to groupings in the ONS taxonomy."
  version: 0.1.0
  license:
    name: "MIT License"
schemes:
  - http
paths:
  /categories/{cat}:
    get:
      summary: match queries on the ONS Website to groupings in the ONS taxonomy
      description: Returns matches and categorises them into groups with a score based on relevancy 
      produces:
        - application/json
      parameters:
        - in: path
          name: cat
          required: true
          type: "string"
          description: "Cateory to search for"
        - in: query
          name: query
          required: false
          type: "string"
          description: query word for that category
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/categoryResponse"
        500:
          $ref: '#/responses/InternalError'
          
  /categories:
    get:
      summary: match queries on the ONS Website to groupings in the ONS taxonomy
      description: Returns matches and categorises them into groups with a score based on relevancy 
      produces:
        - application/json
      parameters:
        - in: query
          name: query
          required: true
          type: "string"
          description: "The query string to search data by"
        - in: query
          name: snr
          required: false
          type: "integer"
          description: signal to noise ratio, how much, above the average, is a score considered a hit
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/categoriesResponse"
          examples:
            application/json:
              matches:
                - s: 27
                  c: pharmacuticalcompanies
                - s: 31
                  c: dentalcare
        500:
          $ref: '#/responses/InternalError'

  /health:
    get:
      tags:
        - private
      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:
  categoriesResponse:
    type: "array"
    items:
      properties:
        s:
          type: "string"
        c:
          type: "string"
          
  categoryResponse:
    type: "array"
    items:
      properties:
        weightings:
          type: "object"
          properties:
            w:
              type: array
              items:
                type: "string"
        scoring:
          type: object
          properties:
            w:
              type: object
              properties:
                overall:
                  type: number
                vector:
                  type: number
                significance:
                  type: number
                by-classifier:
                  type: array
                  items: 
                    type: number

  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 external service used by API"
        enum: ["mongodb"]
      status:
        type: string
        description: "The status of the external service"
        enum: ["OK", "WARNING", "CRITICAL"]
      message:
        type: string
        description: "The message status of the external service"
        example: "mongodb is OK"
      last_checked:
        type: string
        description: "The last health check date and time of the external service"
        example: "2020-06-11T11:49:50.330089Z"
      last_success:
        type: string
        description: "The last successful health check date and time of the external service"
        example: "2020-06-11T11:49:50.330089Z"
      last_failure:
        type: string
        description: "The last failed health check date and time of the external service"
        example: "2019-09-22T11:48:51.0000001Z"