swagger.yml

swagger: "2.0"
info:
  description: "A service used to download files from private or public s3 buckets."
  version: "1.0.0"
  title: "Download service"
  license:
    name: "Open Government Licence v3.0"
    url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"

tags:
  - name: "Public"
schemes:
  - "http"
host: localhost:23600

parameters:
  datasetID:
    name: datasetID
    description: "The unique identifier for a dataset."
    in: path
    required: true
    type: string
  edition:
    name: edition
    description: "An edition of a dataset"
    in: path
    required: true
    type: string
  version:
    name: version
    description: "A version of a dataset"
    in: path
    required: true
    type: string
  filterOutputID:
    name: filterOutputID
    description: "The unique identifier for a filter output job"
    in: path
    required: true
    type: string
  imageID:
    name: imageID
    description: "The unique identifier for an image."
    in: path
    required: true
    type: string
  variant:
    name: variant
    description: "The variant of an image to download"
    in: path
    required: true
    type: string
  filename:
    name: filename
    description: "The filename of the file to download"
    in: path
    required: true
    type: string
  file_path:
    name: filepath
    in: path
    required: true
    description: filepath of required file
securityDefinitions:
  FlorenceAPIKey:
    name: X-Florence-Token
    description: "API key used to allow florence users to be able to access a full download for an unpublished version."
    in: header
    type: apiKey

paths:
  /downloads-new/{filepath}:
    get:
      tags:
        - Download file
      summary: "Download a file"
      description: "Request a download for a file."
      parameters:
        - $ref: '#/parameters/file_path'
          required: true
      produces:
        - "*/*"
      responses:
        200:
          $ref: '#/responses/StreamedResponse'
        301:
          $ref: '#/responses/RequestRedirect'
        400:
          $ref: '#/responses/InvalidRequestError'
        404:
          $ref: '#/responses/NotFoundError'
        500:
          $ref: '#/responses/InternalError'

  /downloads/datasets/{datasetID}/editions/{edition}/versions/{version}.csv:
    get:
      deprecated: true
      tags:
        - "Public"
      summary: "Download the full csv for a given datasetID, edition and version"
      description: "Request a download for the full CSV for a given datasetID, edition and version."
      parameters:
        - $ref: '#/parameters/datasetID'
        - $ref: '#/parameters/edition'
        - $ref: '#/parameters/version'
      produces:
        - "text/csv"
      responses:
        200:
          $ref: '#/responses/StreamedResponse'
        301:
          $ref: '#/responses/RequestRedirect'
        400:
          $ref: '#/responses/InvalidRequestError'
        404:
          $ref: '#/responses/NotFoundError'
        500:
          $ref: '#/responses/InternalError'
  /downloads/datasets/{datasetID}/editions/{edition}/versions/{version}.csv-metadata.json:
    get:
      deprecated: true
      tags:
        - "Public"
      summary: "Download the csv metadata for a given datasetID, edition and version"
      description: "Request a download for the metadata for the full CSV for a given datasetID, edition and version."
      parameters:
        - $ref: '#/parameters/datasetID'
        - $ref: '#/parameters/edition'
        - $ref: '#/parameters/version'
      produces:
        - "application/csvm+json"
      responses:
        200:
          $ref: '#/responses/StreamedResponse'
        301:
          $ref: '#/responses/RequestRedirect'
        400:
          $ref: '#/responses/InvalidRequestError'
        404:
          $ref: '#/responses/NotFoundError'
        500:
          $ref: '#/responses/InternalError'
  /downloads/datasets/{datasetID}/editions/{edition}/versions/{version}.xlsx:
    get:
      deprecated: true
      tags:
        - "Public"
      summary: "Download the full excel file for a given datasetID, edition and version"
      description: "Request a download for the full Excel file for a given datasetID, edition and version."
      parameters:
        - $ref: '#/parameters/datasetID'
        - $ref: '#/parameters/edition'
        - $ref: '#/parameters/version'
      produces:
        - "application/vnd.ms-excel"
      responses:
        200:
          $ref: '#/responses/StreamedResponse'
        301:
          $ref: '#/responses/RequestRedirect'
        400:
          $ref: '#/responses/InvalidRequestError'
        404:
          $ref: '#/responses/NotFoundError'
        500:
          $ref: '#/responses/InternalError'
  /downloads/filter-outputs/{filterOutputID}.csv:
    get:
      deprecated: true
      tags:
        - "Public"
      summary: "Download a filtered csv file for a given filter output id"
      description: "Request a download for a filtered csv file for a given filter ouput id which has selected dimension values"
      parameters:
        - $ref: '#/parameters/filterOutputID'
      produces:
        - "text/csv"
      responses:
        200:
          $ref: '#/responses/StreamedResponse'
        301:
          $ref: '#/responses/RequestRedirect'
        400:
          $ref: '#/responses/InvalidRequestError'
        404:
          $ref: '#/responses/NotFoundError'
        500:
          $ref: '#/responses/InternalError'
  /downloads/filter-outputs/{filterOutputID}.xlsx:
    get:
      deprecated: true
      tags:
        - "Public"
      summary: "Download a filtered excel file for a given filter output id"
      description: "Request a download for a filtered excel file for a given filter ouput id which has selected dimension values"
      parameters:
        - $ref: '#/parameters/filterOutputID'
      produces:
        - "text/csv"
      responses:
        200:
          $ref: '#/responses/StreamedResponse'
        301:
          $ref: '#/responses/RequestRedirect'
        400:
          $ref: '#/responses/InvalidRequestError'
        404:
          $ref: '#/responses/NotFoundError'
        500:
          $ref: '#/responses/InternalError'
  /images/{imageID}/{variant}/{filename}:
    get:
      deprecated: true
      tags:
        - "Public"
      summary: "Download an image variant"
      description: "Request a download of a specific variant of an image as created by the image importer"
      parameters:
        - $ref: '#/parameters/imageID'
        - $ref: '#/parameters/variant'
        - $ref: '#/parameters/filename'
      produces:
        - "image/png"
      responses:
        200:
          $ref: '#/responses/StreamedResponse'
        301:
          $ref: '#/responses/RequestRedirect'
        400:
          $ref: '#/responses/InvalidRequestError'
        404:
          $ref: '#/responses/NotFoundError'
        500:
          $ref: '#/responses/InternalError'

responses:
  InvalidRequestError:
    description: "Failed to process the request due to invalid request."
  InternalError:
    description: "Failed to process the request due to an internal error."
  NotFoundError:
    description: "The download for the requested version was not found."
  RequestRedirect:
    description: "A permanent redirect to where the file is hosted on S3"
  StreamedResponse:
    description: "A streamed response containing the requested download file"
    schema:
      type: file