swagger.yaml

swagger: "2.0"
info:
  title: "dis-migration-service"
  description: "A Go API for data migration."
  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:
  - https
tags:
  - name: "private"
    description: "Private endpoints"
paths:
  /migration-jobs:
    get:
      security:
        - Authorization: [migration:read]
      tags:
        - private
      summary: "Get list of migration jobs"
      description: "Lists all migration jobs in a paginated format."
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/state"
        - $ref: "#/parameters/sort"
      responses:
        200:
          description: "Successful response"
          schema:
            $ref: "#/definitions/MigrationJobList"
        400:
          description: "Invalid request parameter(s)"
          schema:
            $ref: "#/definitions/ErrorList"
        401:
          $ref: "#/responses/Unauthenticated"
        403:
          $ref: "#/responses/Forbidden"
        500:
          $ref: "#/responses/Error"

    post:
      security:
        - Authorization: [migration:create]
      tags:
        - private
      summary: "Create a migration job"
      description: "Creates a migration job using body data."
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: "#/parameters/dry_run"
        - $ref: "#/parameters/MigrationJobPostBody"
      responses:
        200:
          description: "Successful dry run response"
          schema:
            $ref: "#/definitions/MigrationJobPreview"
        202:
          description: "Successful task acceptance"
          schema:
            $ref: "#/definitions/MigrationJob"
        400:
          description: "Invalid request body or source title not found"
          schema:
            $ref: "#/definitions/ErrorList"
        401:
          $ref: "#/responses/Unauthenticated"
        403:
          $ref: "#/responses/Forbidden"
        409:
          description: "Already running job with these parameters"
          schema:
            $ref: "#/definitions/ErrorList"
        500:
          $ref: "#/responses/Error"

  /migration-jobs/{job_number}:
    get:
      security:
        - Authorization: [migration:read]
      tags:
        - private
      summary: "Get a migration job"
      description: "Gets a specific migration job using the unique job number"
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/job_number"
      responses:
        200:
          description: "Successful response"
          schema:
            $ref: "#/definitions/MigrationJob"
        401:
          $ref: "#/responses/Unauthenticated"
        403:
          $ref: "#/responses/Forbidden"
        404:
          description: "Migration Job not found"
          schema:
            $ref: "#/definitions/ErrorList"
        500:
          $ref: "#/responses/Error"

  /migration-jobs/{job_number}/state:
    put:
      security:
        - Authorization: [migration:edit]
      tags:
        - private
      summary: "Updates a migration state"
      description: "Updates the state of a specific migration job using the unique job number"
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - $ref: "#/parameters/job_number"
        - $ref: "#/parameters/MigrationJobState"
      responses:
        204:
          description: "Successful state change"
        400:
          description: "Invalid state supplied"
          schema:
            $ref: "#/definitions/ErrorList"
        401:
          $ref: "#/responses/Unauthenticated"
        403:
          $ref: "#/responses/Forbidden"
        404:
          description: "Migration job not found"
          schema:
            $ref: "#/definitions/ErrorList"
        409:
          description: "State change is not allowed"
          schema:
            $ref: "#/definitions/ErrorList"
        500:
          $ref: "#/responses/Error"

  /migration-jobs/{job_number}/events:
    get:
      security:
        - Authorization: [migration:read]
      tags:
        - private
      summary: "Gets a migration job's events"
      description: >
        "Gets a specific migration job using the unique job number and returns 
        it's events (state changes) in a paginated list"
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/job_number"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
      responses:
        200:
          description: "Successful response"
          schema:
            $ref: "#/definitions/MigrationJobEventList"
        400:
          description: "Invalid request parameter(s)"
          schema:
            $ref: "#/definitions/ErrorList"
        401:
          $ref: "#/responses/Unauthenticated"
        403:
          $ref: "#/responses/Forbidden"
        404:
          description: "Migration job not found"
          schema:
            $ref: "#/definitions/ErrorList"
        500:
          $ref: "#/responses/Error"

  /migration-jobs/{job_number}/tasks:
    get:
      security:
        - Authorization: [migration:read]
      tags:
        - private
      summary: "Gets a migration job's tasks"
      description: >
        "Gets a specific migration job using the unique job number and returns 
        it's tasks in a paginated list"
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/job_number"
        - $ref: "#/parameters/limit"
        - $ref: "#/parameters/offset"
        - $ref: "#/parameters/state"
      responses:
        200:
          description: "Successful response"
          schema:
            $ref: "#/definitions/MigrationTaskList"
        400:
          description: "Invalid request parameter(s)"
          schema:
            $ref: "#/definitions/ErrorList"
        401:
          $ref: "#/responses/Unauthenticated"
        403:
          $ref: "#/responses/Forbidden"
        404:
          description: "Migration job not found"
          schema:
            $ref: "#/definitions/ErrorList"
        500:
          $ref: "#/responses/Error"

  /health:
    get:
      security: []
      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/Error"

parameters:
  dry_run:
    in: query
    name: dry_run
    description: >
      A modifier for creation to see what would be created if done.
    type: boolean
    required: false
  job_id:
    in: path
    name: job_id
    description: "Unique identifier for a migration job"
    type: string
    required: true
  job_number:
    in: path
    name: job_number
    description: "Unique human-readable identifier for a migration job"
    type: integer
    required: true
  limit:
    name: limit
    in: query
    description: "The number of items requested, defaulted to 10 and limited to 1000."
    type: integer
    required: false
    default: 10
  offset:
    in: query
    name: offset
    description: >
      The offset into the complete ordered set of items which satisfy the query, which specifies the 
      first item to return (starting at 0). Use this parameter as a pagination mechanism along with 
      the limit parameter."
    type: integer
    required: false
    default: 0
  state:
    in: query
    name: state
    description: >
      A filter for item state, specifies a subset of items to be returned"
    type: string
    enum: &STATE
      - submitted
      - in_review
      - approved
      - published
      - completed
      # Running states
      - migrating
      - publishing
      - post_publishing
      - reverting
      # Failed states
      - failed_post_publish
      - failed_publish
      - failed_migration
      - cancelled
    required: false
  sort:
    in: query
    name: sort
    description: >
      Sort jobs by `job_number` or `label` in ascending (`asc`) or descending (`desc`) order.
      
      Format: `$field:$direction`
    type: string
    enum:
      - job_number:asc
      - job_number:desc
      - label:asc
      - label:desc
    required: false
    default: job_number:desc
  MigrationJobPostBody:
    in: body
    name: body
    schema:
      type: object
      properties:
        source_id:
          type: string
        target_id:
          type: string
        type:
          $ref: "#/definitions/MigrationJobType"
      required:
        - source_id
        - type
  MigrationJobState:
    in: body
    name: body
    schema:
      type: object
      properties:
        state:
          type: string
          enum:
            - approved
            - cancelled

responses:
  Unauthenticated:
    description: "Request is not authenticated"
    schema:
      $ref: "#/definitions/ErrorList"
  Forbidden:
    description: "Request is not authorised"
    schema:
      $ref: "#/definitions/ErrorList"
  Error:
    description: "Generic error response"
    schema:
      $ref: "#/definitions/ErrorList"

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
            format: date-time
            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.25.1"
          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
        format: date-time
        description: "The last health check date and time of the external service"
        example: "2020-06-11T11:49:50.330089Z"
      last_success:
        type: string
        format: date-time
        description: "The last successful health check date and time of the external service"
        example: "2020-06-11T11:49:50.330089Z"
      last_failure:
        type: string
        format: date-time
        description: "The last failed health check date and time of the external service"
        example: "2019-09-22T11:48:51.0000001Z"

  MigrationJob:
    type: object
    properties:
      job_number:
        type: integer
        example: 20
      last_updated:
        type: string
        format: date-time
        example: "2020-06-11T12:49:20+01:00"
      label:
        type: string
        description: "The title of the source dataset, automatically populated during job creation"
        example: "Consumer Price Index: All Items"
      links:
        type: object
        properties:
          events:
            description: "A link to all the events for the migration job"
            type: object
            properties:
              href:
                description: "A fully qualified URL to the migration job's events API response"
                type: string
                example: "https://api.beta.ons.gov.uk/v1/migration-jobs/20/events"
          self:
            description: "A link to the individual migration job"
            type: object
            properties:
              href:
                description: "A fully qualified URL to the migration job API response"
                type: string
                example: "https://api.beta.ons.gov.uk/v1/migration-jobs/20"
              job_number:
                type: integer
                example: 20
          tasks:
            description: "A link to all the tasks for the migration job"
            type: object
            properties:
              href:
                description: "A fully qualified URL to the migration job's tasks API response"
                type: string
                example: "https://api.beta.ons.gov.uk/v1/migration-jobs/20/tasks"
      config:
        description: "Config for the job"
        $ref: "#/definitions/MigrationJobConfig"
      state:
        $ref: "#/definitions/MigrationState"
      type:
        $ref: "#/definitions/MigrationJobType"

  MigrationJobConfig:
    type: object
    properties:
      collection_id:
        type: string
        example: "migration-collection-20"
      source_id:
        type: string
        example: "/economy/inflationandpriceindices"
      target_id:
        type: string
        example: "migration-series-id"
      type:
        $ref: "#/definitions/MigrationJobType"

  MigrationJobPreview:
    type: object
    properties:
      allOf:
        $ref: "#/definitions/MigrationJob"
      tasks:
        type: array
        items:
          $ref: "#/definitions/MigrationTask"

  MigrationTask:
    type: object
    properties:
      id:
        type: string
        example: 1
      last_updated:
        type: string
        format: date-time
        example: "2020-06-11T12:49:20+01:00"
      source:
        $ref: "#/definitions/MigrationTaskMetadata"
      state:
        $ref: "#/definitions/MigrationState"
      target:
        $ref: "#/definitions/MigrationTaskMetadata"
      type:
        $ref: "#/definitions/MigrationTaskType"

  MigrationTaskMetadata:
    type: object
    properties:
      id:
        type: string
        example: 1
      label:
        type: string
        example: "Consumer price inflation tables"
      dataset_id:
        type: string
        example: "consumer-price-inflation"

  MigrationJobList:
    allOf:
      - $ref: "#/definitions/List"
      - type: object
        properties:
          items:
            type: array
            description: Array containing results.
            items:
              $ref: "#/definitions/MigrationJob"

  MigrationTaskList:
    allOf:
      - $ref: "#/definitions/List"
      - type: object
        properties:
          items:
            type: array
            description: Array containing results.
            items:
              $ref: "#/definitions/MigrationTask"

  MigrationJobEventList:
    allOf:
      - $ref: "#/definitions/List"
      - type: object
        properties:
          items:
            type: array
            description: Array containing results.
            items:
              $ref: "#/definitions/MigrationJobEvent"

  MigrationJobEvent:
    description: Details of a specific change event forming part of the change and audit log for a migration job.
    type: object
    properties:
      created_at:
        description: The date and time the event occurred.
        type: string
        format: date-time
        example: "2020-06-11T12:49:20+01:00"
      requested_by:
        description: The user who made the request.
        type: object
        properties:
          id:
            description: The ID of the user.
            type: string
            example: 0889d599-3f0e-4564-9d6e-9455a6b73da7
          email:
            description: The email of the user. This is only populated if the user is a human user.
            type: string
            format: email
            example: publisher@ons.gov.uk
      action:
        description: The action taken by the user.
        type: string
        enum: *STATE
      jobId:
        description: The ID of the job this event took place on.
        type: string
        example: 1

  List:
    type: object
    properties:
      count:
        type: integer
        description: How many jobs are present in the response
      limit:
        type: integer
        description: Max number of jobs we are returning with this response
      offset:
        type: integer
        description: The number of documents into the full list this response started at
      total_count:
        type: integer
        description: How many jobs are available in total

  MigrationState:
    type: string
    enum: *STATE

  MigrationJobType:
    type: string
    enum:
      - static_dataset

  MigrationTaskType:
    type: string
    enum:
      - dataset_series
      - dataset_edition
      - dataset_version
      - dataset_download

  ErrorList:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/Error'

  Error:
    type: object
    properties:
      code:
        type: integer
        description: "Code representing the type of error that occurred"
      description:
        type: string
        description: "Description of the error"

securityDefinitions:
  Authorization:
    name: Authorization
    description: "Service Auth Token used by Auth service"
    in: header
    type: apiKey