swagger.yaml

swagger: "2.0"
info:
  description: "Search API"
  version: "1.0.0"
  title: "dp-search-api"
  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"
  - name: "private"
paths:
  /departments/search:
    get:
      tags:
        - public
      summary: "Department query API"
      description: "Department query API which returns matching links to other departments"
      parameters:
        - in: query
          name: q
          description: "Query search term"
          type: string
          required: true
        - in: query
          name: limit
          description: "The number of items requested, defaulted to 50 and limited to 1000."
          type: integer
          required: false
        - in: query
          name: offset
          description: "The first row of resources to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter."
          type: integer
          required: false
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/DepartmentResponse"
        400:
          description: Query term not specified
        500:
          description: Internal server error

  /health:
    get:
      tags:
        - public
      summary: "Health check API"
      description: "API to query the app for current health status"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/Health"
        500:
          description: Internal Server Error

  /search:
    get:
      tags:
        - public
      summary: "Default ONS query API"
      description: "Default ONS query API which combines the content with type counts"
      parameters:
        - in: query
          name: q
          description: "Query search term."
          type: string
          required: true
        - in: query   
          name: content_type
          description: "Comma separated list of content types to be returned."
          type: array
          uniqueItems: true
          items:
            type: string
          collectionFormat: csv
          required: false
        - in: query
          name: topics
          description: "Comma separated list of topics to be returned."
          type: array
          uniqueItems: true
          items:
            type: string
          collectionFormat: csv
          required: false
        - in: query
          name: population_types
          description: "Comma separated list of population type names to filter the results (or)."
          type: array
          uniqueItems: true
          items:
            type: string
          collectionFormat: csv
          required: false
        - in: query
          name: dimensions
          description: "Comma separated list of dimension names to filter the results (and)."
          type: array
          uniqueItems: true
          items:
            type: string
          required: false
          collectionFormat: csv
        - in: query
          name: highlight
          description: "Determines whether to return HTML highlighted fields."
          type: boolean
          required: false
          default: true
        - in: query
          name: sort
          description: "The order to return the results."
          type: string
          required: false
        - in: query
          name: limit
          description: "The number of items requested, defaulted to 50 and limited to 1000."
          type: integer
          required: false
        - in: query
          name: offset
          description: "The first row of resources to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter."
          type: integer
          required: false
        - in: query
          name: fromDate
          description: "Specifies candidate results by their ReleaseDate, which must be on or after the fromDate"
          type: string
          required: false
        - in: query
          name: toDate
          description: "Specifies candidate results by their ReleaseDate, which must be on or before the toDate"
          type: string
          required: false
        - in: query
          name: nlp_weighting
          description: "Runs query through NLP processors to influence search weighting"
          type: boolean
          required: false
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/GetSearchResponse"
        400:
          description: Query term not specified
        500:
          description: Internal server error
    post:
     tags:
       - private
     summary: "Create new empty ONS Elasticsearch index"
     description: "Request a new search index and receive the name of the new index created in response. Endpoint requires service or user authentication."
     responses:
       200:
         description: OK
         schema:
           $ref: "#/definitions/PostSearchResponse"
       500:
         description: Internal server error

  /search/releases:
    get:
      tags:
        - public
      summary: "ONS query API for published or upcoming releases"
      description: "ONS query API specifically targeting already Published (or Cancelled) Releases, or upcoming Release Calendar Entries"
      parameters:
        - in: query
          name: limit
          description: "The number of Resources requested, defaulted to 10 and limited to 1000."
          type: integer
          required: false
          default: 10
        - in: query
          name: offset
          description: "The offset into the complete ordered set of Resources which satisfy the query, which specifies the first Resource to return (starting at 0). Use this parameter as a pagination mechanism along with the limit parameter."
          type: integer
          required: false
          default: 0
        - in: query
          name: sort
          description: "The sort order of the returned set of Releases"
          type: string
          required: false
          default: "release_date_asc"
        - in: query
          name: q
          description: "Query keywords"
          type: string
          required: false
        - in: query
          name: fromDate
          description: "Specifies candidate Releases by their ReleaseDate, which must be on or after the fromDate"
          type: string
          required: false
        - in: query
          name: toDate
          description: "Specifies candidate Releases by their ReleaseDate, which must be on or before the toDate"
          type: string
          required: false
        - in: query
          name: upcoming
          description: "Determines whether to return Upcoming Release Calendar Entries or Published Releases"
          type: boolean
          required: false
          default: false
        - in: query
          name: highlight
          description: "Determines whether to return HTML highlighted fields."
          type: boolean
          required: false
          default: true
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/SearchReleaseResponse"
        500:
          description: Internal server 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 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"

  GetSearchResponse:
    type: object
    properties:
      count:
        type: number
        description: "Number of search results which match query"
        example: 80
      took:
        type: number
        description: "Time taken to execute query in milliseconds"
        example: 530
      dimensions:
        type: array
        description: "List of population types included in results"
        items:
          $ref: "#/definitions/CountItem"
      content_types:
        type: array
        description: "List of content types included in results"
        items:
          $ref: "#/definitions/CountItem"
      population_types:
        type: array
        description: "List of population types included in results"
        items:
          $ref: "#/definitions/CountItem"
      topics:
        type: array
        description: "List of topics included in results"
        items:
          $ref: "#/definitions/CountItem"
      items:
        type: array
        description: "List of matching content items for the current page"
        items:
          $ref: "#/definitions/ContentItem"
      suggestions:
        type: array
        description: "List of suggested alternative similar search queries"
        items:
          type: string
      alternative_suggestions:
        type: array
        description: "List of suggested alternative search queries from current search query"
        items:
          type: string
        example: ['UK', 'economy', "inflation rate"]
    required:
      - count
      - took
      - content_types
      - items

  PostSearchResponse:
    type: object
    properties:
      index_name:
        type: string
        description: "Name of new empty search index"
        example: "ons1636458168532"
    required:
      - index_name

  SearchReleaseResponse:
    type: object
    properties:
      took:
        type: number
        description: "Time taken to execute query in milliseconds"
        example: 530
      limit:
        type: number
        description: "The number of Releases returned in the payload"
        example: 10
      offset:
        type: number
        description: "The offset of the first Release in the releases payload from the first Release in the complete ordered set of Releases which match the query"
        example: 130
      breakdown:
        description: "Breakdown of the total number of Releases into defined categories"
        $ref: "#/definitions/Breakdown"
      releases:
          type: array
          description: "List of matching Releases"
          items:
            $ref: "#/definitions/Release"
    required:
      - took
      - limit
      - offset
      - breakdown
      - releases

  Breakdown:
    type: object
    properties:
      total:
        type: number
        description: "Total number of Releases which match query"
        example: 80
      provisional:
        type: number
        description: "Number of provisional Releases"
        example: 5
      confirmed:
        type: number
        description: "Number of confirmed Releases"
        example: 5
      postponed:
        type: number
        description: "Number of postponed Releases"
        example: 5
      published:
        type: number
        description: "Number of published Releases"
        example: 5
      cancelled:
        type: number
        description: "Number of cancelled Releases"
        example: 5
      census:
        type: number
        description: "Number of Releases that are related to Census"
        example: 5
    required:
      - total

  DepartmentResponse:
    type: object
    properties:
      count:
        type: number
        description: "Number of search results which match query"
        example: 80
      took:
        type: number
        description: "Time taken to execute query in milliseconds"
        example: 530
      items:
        type: array
        description: "List of matching content items for the current page"
        items:
          $ref: "#/definitions/DepartmentItem"
    required:
      - count
      - took

  Dimension: 
    type: object
    properties:
      label:
        type: string
      raw_label:
        type: string
      name:
        type: string

  ContentItem:
    type: object
    properties:
      description:
        type: object
        properties:
          contact:
            type: object
            properties:
              email:
                type: string
              name:
                type: string
              telephone:
                type: string
            required:
              - name
              - email
          dataset_id:
            type: string
          dimensions:
            type: array
            items:
              $ref: "#/definitions/Dimension"
            description: "An array of dimensions within a dataset."
          edition:
            type: string
          highlight:
            $ref: "#/definitions/Highlight"
          headline1:
            type: string
          headline2:
            type: string
          headline3:
            type: string
          keywords:
            type: array
            items:
              type: string
          latest_release:
            type: boolean
          language:
            type: string
            example: "English"
          meta_description:
            type: string
          national_statistic:
            type: boolean
          next_release:
            type: string
            example: "14 August 2015"
          population_type:
            type: string
            description: "A population type a dataset is associated with e.g. Usual-Residents.  This is applicable to Census 2021 datasets only."
          pre_unit:
            type: string
          release_date:
            type: string
            format: date-time
          source:
            type: string
          summary:
            type: string
          title:
            type: string
          topics:
            type: array
            items:
              type: string
          unit:
            type: string

        required:
          - summary
          - title
      type:
        type: string
      uri:
        type: string
    required:
      - description
      - type
      - uri

  CountItem:
    type: object
    properties:
      type:
        type: string
      count:
        type: integer
    required:
      - "type"
      - "count"

  Release:
    type: object
    properties:
      description:
        type: object
        properties:
          cancelled:
            type: boolean
          cancellation_notice:
            type: array
            items:
              type: string
          census:
            type: boolean
          contact:
            type: object
            properties:
              email:
                type: string
              name:
                type: string
              telephone:
                type: string
            required:
              - name
              - email
          dataset_id:
            type: string
          edition:
            type: string
          finalised:
              type: boolean
          keywords:
            type: array
            items:
              type: string
          latest_release:
            type: boolean
          language:
            type: string
            example: "English"
          meta_description:
            type: string
          national_statistic:
            type: boolean
          next_release:
            type: string
            example: "14 August 2015"
          postponed:
            type: boolean
          provisional_date:
            type: string
            format: date-time
          published:
            type: boolean
          release_date:
            type: string
            format: date-time
          source:
            type: string
          summary:
            type: string
          title:
            type: string
        required:
          - cancelled
          - census
          - finalised
          - postponed
          - published
          - release_date
          - summary
          - title
      highlight:
        $ref: "#/definitions/Highlight"
      uri:
        type: string
    required:
      - description
      - uri

  Highlight:
    description: "Fields that contain at least 1 matching term from query 'q' parameter. The values contain the following embedded tags \"...<em class=\"highlight\">{matched term}</em>...\""
    type: object
    properties:
      dataset_id:
        type: string
      edition:
        type: string
      keywords:
        type: array
        items:
          type: string
      meta_description:
        type: string
      summary:
        type: string
      title:
        type: string
      topics:
        type: array
        items:
          type: string

  DepartmentItem:
    type: object
    properties:
      code:
        type: string
      name:
        type: string
      url:
        type: string
      terms:
        type: array
        items:
          type: string
      matches:
        type: array
        items:
          type: object
          properties:
            terms:
              type: array
              items:
                type: string