swagger.yaml

swagger: "2.0"
basePath: /v1
info:
  title: "dp-nlp-berlin-api"
  description: "A Python microservice to wrap the Berlin package for identifying locations and tagging them with UN-LOCODEs and ISO-3166-2 subdivisions."
  version: 1.0.0
  license:
    name: "MIT License"
schemes:
  - http
paths:
  /berlin/code/{code}:
    get:
      summary: retrieve an individual code by its identifier
      description: Returns information about a code, if it exists
      produces:
        - application/json
      parameters:
        - in: path
          name: code
          description: "The query string to search data by"
          required: true
          type: "string"
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/location_codes"
          examples:
            application/json:
              matches:
                - encoding: "UN-LOCODE"
                  id: "ca:lod"
                  key: "UN-LOCODE-ca:lod"
                  words:
                    - "london"
                  names:
                    - "london"
                  codes:
                    - "lod"
                  state:
                    - "ca"
                    - "canada"
                  subdiv:
                    - "on"
                    - "ontario"
                - encoding:	"UN-LOCODE"
                  id:	"us:ldn"
                  key:	"UN-LOCODE-us:ldn"
                  words:	
                    -	"london"
                  names:
                    - "london"
                  codes:
                    - "ldn"
                  state:
                    - "us"
                    - "united states of america"
                  subdiv:
                    - "oh"
                    - "ohio"
        404:
          $ref: '#/responses/NotFound'
        500:
          $ref: '#/responses/InternalError'

  /berlin/search:
    get:
      summary: identifies locations and tagging them with UN-LOCODEs and ISO-3166-2 subdivisions 
      description: Returns UN-LOCODEs and ISO3166-2 subdivisions
      produces:
        - application/json
      parameters:
        - in: query
          name: q
          description: "The query string to search data by"
          required: true
          type: "string"
        - in: query
          type: "integer"
          required: false
          name: limit
          description: limits the data returned in the response
        - in: query
          type: "string"
          required: false
          name: state
          description: let's you specify in which state are you looking for that specific location
        - in: query
          type: "integer"
          required: false
          name: lev_distance
          description: do a fuzzy search via a Levenshtein distance enabled finite-state transducer. The pre-filtered results are passed through a string-similarity evaluation algorithm and sorted by score
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/matches"
          examples:
            application/json:
              matches:
                - encoding: "UN-LOCODE"
                  id: "ca:lod"
                  key: "UN-LOCODE-ca:lod"
                  words:
                    - "london"
                - encoding:	"UN-LOCODE"
                  id:	"us:ldn"
                  key:	"UN-LOCODE-us:ldn"
                  words:	
                    -	"london"
        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:
  NotFound:
    description: "Resource not found"
  InternalError:
    description: "Failed to process the request due to an internal error"

definitions:
  matches:
    type: "array"
    items:
        $ref: "#/definitions/location_codes"
  location_codes:
    type: "object"
    properties:
      encoding:
        type: "string"
      id:
        type: "string"
      key:
        type: "string"
      words:
        type: "array"
        items: 
          type: "string"
      subdiv:
        type: "array"
        items: 
          type: "string"
      state:
        type: "array"
        items: 
          type: "string"
      names:
        type: "array"
        items: 
          type: "string"
      codes:
        type: "array"
        items: 
          type: "string"
  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"