---
openapi: "3.0.2"
info:
  version: 0.1.0
  title: ImageMuck
  description: >-
    A simple HTTP service for mucking about with images. This is a super basic HTTP
    service for autogenerating website ready banner and preview images from full-size
    source images. The generated images are automatically cached with deterministic
    URLs.
  license:
    name: MIT
    url: https://mit-license.org/
x-anchors:
  DefaultHeaders: &headers-default
    x-imagemuck-version:
      $ref: "#/components/headers/Version"
  OptionsResponses: &responses-options
    '204':
      description: "Available HTTP verbs in header, per RFC 7231"
      headers:
        Allowed:
          $ref: "#/components/headers/Allowed"
    '500':
      $ref: "#/components/responses/InternalServerError"
paths:
  /openapi.json:
    get:
      summary: Retrieve the OpenAPI specification file
      operationId: OpenAPI
      tags: ["meta"]
      responses:
        '200':
          description: Contents of the OpenAPI spec file
          headers: *headers-default
          content:
            application/json:
              schema:
                type: object
  /image/{image_name}.{format}:
    get:
      summary: Retrieve the image resource with the specified ID
      operationId: ImageGet
      tags: ["image"]
      parameters:
        - $ref: "#/components/parameters/ImageName"
        - $ref: "#/components/parameters/ImageFormat"
      responses:
        '200':
          description: Image content for provided ID
          headers: *headers-default
          content:
            image/jpeg: {}
            image/png: {}
        '404':
          $ref: "#/components/responses/NotFoundError"
        '410':
          $ref: "#/components/responses/DeletedError"
        '500':
          $ref: "#/components/responses/InternalServerError"
    post:
      summary: Upload an image to the server
      operationId: ImageUpload
      tags: ["image"]
      parameters:
        - $ref: "#/components/parameters/ImageName"
        - $ref: "#/components/parameters/ImageFormat"
      responses:
        '201':
          description: Image uploaded successfully
        '405':
          $ref: "#/components/responses/MethodNotAllowedError"
        '406':
          description: Image is not acceptable for upload
          headers: *headers-default
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '409':
          description: Image with provided ID already exists
          headers: *headers-default
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '413':
          description: Image is too large for upload
          headers: *headers-default
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        '500':
          $ref: "#/components/responses/InternalServerError"
    delete:
      summary: Delete an image from the server
      operationId: ImageDelete
      tags: ["image", "manipulate"]
      parameters:
        - $ref: "#/components/parameters/ImageName"
        - $ref: "#/components/parameters/ImageFormat"
      responses:
        '204':
          description: Image with provided ID successfully deleted
          headers: *headers-default
        '404':
          $ref: "#/components/responses/NotFoundError"
        '405':
          $ref: "#/components/responses/MethodNotAllowedError"
        '410':
          $ref: "#/components/responses/DeletedError"
        '500':
          $ref: "#/components/responses/InternalServerError"
    options:
      summary: Retrieve available HTTP verbs for the selected endpoint
      operationId: ImageOptions
      tags: ["meta"]
      parameters:
        - $ref: "#/components/parameters/ImageName"
        - $ref: "#/components/parameters/ImageFormat"
      responses: *responses-options
  /image/{image_name}/{dimension}-{value}.{format}:
    get:
      summary: Fetch a scaled image
      operationId: ThumbnailScale
      tags: ["manipulate"]
      parameters:
        - $ref: "#/components/parameters/ImageName"
        - $ref: "#/components/parameters/ImageFormat"
        - $ref: "#/components/parameters/ImageScaleDimension"
        - $ref: "#/components/parameters/ImageScaleValue"
      responses:
        '200':
          description: Scaled image thumbnail content
          headers: *headers-default
          content:
            image/jpeg: {}
            image/png: {}
        '404':
          $ref: "#/components/responses/NotFoundError"
        '410':
          $ref: "#/components/responses/DeletedError"
        '500':
          $ref: "#/components/responses/InternalServerError"
    options:
      summary: Retrieve available HTTP verbs for the selected endpoint
      operationId: ImageScaleOptions
      tags: ["meta"]
      parameters:
        - $ref: "#/components/parameters/ImageName"
        - $ref: "#/components/parameters/ImageFormat"
        - $ref: "#/components/parameters/ImageScaleDimension"
        - $ref: "#/components/parameters/ImageScaleValue"
      responses: *responses-options
  /image/{image_name}/{anchor}-{width}x{height}.{format}:
    get:
      summary: Fetch a cropped version of the image
      operationId: ImageCrop
      tags: ["manipulate"]
      parameters:
        - $ref: "#/components/parameters/ImageName"
        - $ref: "#/components/parameters/ImageFormat"
        - $ref: "#/components/parameters/ImageCropAnchor"
        - $ref: "#/components/parameters/ImageCropWidth"
        - $ref: "#/components/parameters/ImageCropHeight"
      responses:
        '200':
          description: Scaled thumbnail image of specified dimentions
          headers: *headers-default
          content:
            image/jpeg: {}
            image/png: {}
        '404':
          $ref: "#/components/responses/NotFoundError"
        '410':
          $ref: "#/components/responses/DeletedError"
        '500':
          $ref: "#/components/responses/InternalServerError"
    options:
      summary: Retrieve available HTTP verbs for the selected endpoint
      operationId: ImageCropOptions
      tags: ["meta"]
      parameters:
        - $ref: "#/components/parameters/ImageName"
        - $ref: "#/components/parameters/ImageFormat"
        - $ref: "#/components/parameters/ImageCropAnchor"
        - $ref: "#/components/parameters/ImageCropWidth"
        - $ref: "#/components/parameters/ImageCropHeight"
      responses: *responses-options
components:
  schemas:
    Error:
      type: object
      properties:
        event_id:
          type: string
          format: uuid
        message:
          type: string
        data:
          type: object
      example:
        event_id: 0de388ae-8277-49ba-b225-3ef7f5b9d084
        message: An error ocurred in a backend component
        data: {}
  headers:
    Version:
      description: Keyosk server application version
      schema:
        type: string
    Allowed:
      description: Comma delimited list of valid HTTP verbs
      schema:
        type: string
  parameters:
    ImageName:
      name: image_name
      in: path
      description: Image resource name
      required: true
      schema:
        type: string
    ImageFormat:
      name: format
      in: path
      description: Image format extension
      required: true
      schema:
        type: string
        enum: [jpg, jpeg, png]
    ImageScaleDimension:
      name: dimension
      in: path
      description: Which dimension to scale to the provided dimension
      required: true
      schema:
        type: string
        enum: ["w", "h"]
    ImageScaleValue:
      name: value
      in: path
      description: Dimension in pixels to scale the image to
      required: true
      schema:
        type: number
        format: integer
    ImageCropAnchor:
      name: anchor
      in: path
      description: Anchor point on the image for cropping
      required: true
      schema:
        type: string
        enum: ["tl", "tc", "tr", "cl", "cc", "cr", "bl", "bc", "br"]
    ImageCropWidth:
      name: width
      in: path
      description: Width in pixels of the image thumbnail
      required: true
      schema:
        type: number
        format: integer
    ImageCropHeight:
      name: height
      in: path
      description: Height in pixels of the image thumbnail
      required: true
      schema:
        type: number
        format: integer
  responses:
    InternalServerError:
      description: Internal server error
      headers: *headers-default
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFoundError:
      description: Image with provided ID does not exist
      headers: *headers-default
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    MethodNotAllowedError:
      description: The request's HTTP method is not allowed on this endpoint
      headers: *headers-default
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    DeletedError:
      description: Image with provided ID was deleted
      headers: *headers-default
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"