swagger.yml

openapi: 3.0.0
info:
  title: Fast Purge URLs
  description: Invalidate URLs from Akamai's cache using the Fast Purge API
  license:
    name: MIT
    url: https://github.com/nhsuk/cache-flush/blob/master/LICENSE.md
  version: 0.1.0
servers:
- url: https://api.nhs.uk/
  description: Production server, requires API key
paths:
  /utils/cache-flush:
    post:
      summary: Invalidate a set of URLs from Akamai's cache
      description: Request a set of URLs to be invalidated for the given environment
        from Akamai's cache using Fast Purge API
      operationId: FastPurgeURLs
      requestBody:
        description: Set of URLs to invalidate in the given environment
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FastPurgeRequest'
        required: true
      responses:
        201:
          description: Request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/201Response'
        400:
          description: Object invalid
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/MissingPropertiesResponse'
                  - $ref: '#/components/schemas/InvalidEnvironmentResponse'
                  - $ref: '#/components/schemas/InvalidObjectsResponse'
        403:
          description: URL contains a domain not under our control
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Response'
        500:
          description: Error occurred during request to Akamai
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Response'
components:
  schemas:
    FastPurgeRequest:
      required:
      - environment
      - objects
      type: object
      properties:
        objects:
          type: array
          description: The set of URLs to be invalidated from cache
          example:
          - https://sub.domain.nhs.uk/cached/page/path
          - http://nhs.uk/another/cached/resource.ext
          items:
            type: string
        environment:
          type: string
          description: Akamai environment against which the purge operation should
            execute
          example: production
          enum:
          - staging
          - production
        debug:
          type: boolean
          description: A boolean flag indicating if the request should include debug
            information. Useful for debugging
          default: false
    201Response:
      type: object
      properties:
        detail:
          type: string
          description: Additional detail on the response
          example: Request accepted
        estimatedSeconds:
          type: integer
          description: The estimated number of seconds the request will take to complete
          example: 5
        httpStatus:
          type: integer
          description: The http status code of the response from Akamai
          example: 201
        purgeID:
          type: string
          description: Akamai purge id
          example: e535071c-26b2-11e7-94d7-276f2f54d938
        supportId:
          type: string
          description: Akamai support id
          example: 17PY1492793544958045-219026624
        urls:
          type: array
          description: The set of URLs the request was made for
          example:
          - https://sub.domain.nhs.uk/cached/page/path
          - http://nhs.uk/another/cached/resource.ext
          items:
            type: string
    MissingPropertiesResponse:
      type: object
      properties:
        message:
          type: string
          description: Informative message about why the request was rejected
          example: 'Request must contain a body with required properties: ''environment'', ''objects''.'
    403Response:
      type: object
      properties:
        message:
          type: string
          description: Informative message about why the request was rejected
          example: Some URLs can not be flushed from cache as they are not for the
            domain 'nhs.uk'.
        urls:
          type: array
          description: The set of URLs that do not match the allowed domain
          example:
          - https://not.nhs.uk.domain/cached/page/path
          items:
            type: string
    InvalidObjectsResponse:
      type: object
      properties:
        message:
          type: string
          description: Informative message about why the request was rejected
          example: Some URLs are invalid as they are not parseable into a valid URL.
        urls:
          type: array
          description: The set of URLs that were unable to be parsed into a valid
            URL
          example:
          - not.a.valid.url
          items:
            type: string
    InvalidEnvironmentResponse:
      type: object
      properties:
        message:
          type: string
          description: Informative message about why the request was rejected
          example: '''unknown'' environment is not a valid option for environment.
            It must be one of: ''staging'', ''production''.'
    500Response:
      type: object
      properties:
        message:
          type: string
          description: Informative message about why the request was rejected
          example: An error has occurred during cache flush.
        error:
          $ref: '#/components/schemas/500Response_error'
    500Response_error:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: 'SyntaxError: Unexpected token a in JSON at position 0'
        name:
          type: string
          description: The name of the error
          example: SyntaxError