swagger.yaml

swagger: "2.0"
info:
  title: "dp-feedback-api"
  description: | 
    This API is used to submit feedback from other Dissemination services for internal
    distribution, analysis and action.
  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: "feedback"
  - name: "private"
securityDefinitions:
  AuthorizationToken:
    name: Authorization
    description: "API key used to allow only internal services to post feedback"
    in: header
    type: apiKey
parameters:
  feedback:
    name: feedback
    in: body
    required: true
    schema:
      type: object
      required: 
        - is_page_useful
        - is_general_feedback
        - feedback
      properties:
        is_page_useful:
          type: boolean
        is_general_feedback:
          type: boolean
        name:
          type: string
        email_address:
          type: string
        feedback:
          type: string
        ons_url:
          type: string
          description: "URL the feedback is received from"
paths:
  /feedback:
    post:
      consumes:
        - application/json
      tags:
        - feedback
      summary: "Post feedback for distribution"
      description: "Post feedback forms here for distribution and/or storage internally"
      parameters:
        - $ref: '#/parameters/feedback'
      responses:
        201:
          description: "OK"
        400:
          $ref: '#/responses/InvalidRequestError'
        401:
          $ref: '#/responses/UnauthorisedError'
        500:
          $ref: '#/responses/InternalError'
      security:
        - AuthorizationToken: []
  /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"
  InvalidRequestError:
    description: "Failed to process the request due to an invalid request"
  UnauthorisedError:
    description: "Unauthorised to access resource"

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 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"