1
0
mirror of https://github.com/enpaul/kodak.git synced 2024-11-14 10:36:55 +00:00

Update openapi to simplify structure

Abandon all but the simplest of auth schemas
Remove dynamic image generation
Add support for cache control
Add support for 501, 405, and 422 status codes
This commit is contained in:
Ethan Paul 2021-10-28 18:33:41 -04:00
parent 7b49146123
commit f9c38a5bcc
No known key found for this signature in database
GPG Key ID: D0E2CBF1245E92BF

View File

@ -5,7 +5,7 @@ info:
title: ImageMuck title: ImageMuck
description: >- description: >-
A simple HTTP service for mucking about with images. This is a super basic HTTP 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 service for autogenerating website-ready banner and preview images from full-size
source images. The generated images are automatically cached with deterministic source images. The generated images are automatically cached with deterministic
URLs. URLs.
license: license:
@ -13,7 +13,7 @@ info:
url: https://mit-license.org/ url: https://mit-license.org/
x-anchors: x-anchors:
DefaultHeaders: &headers-default DefaultHeaders: &headers-default
x-imagemuck-version: Server:
$ref: "#/components/headers/Version" $ref: "#/components/headers/Version"
OptionsResponses: &responses-options OptionsResponses: &responses-options
'204': '204':
@ -23,6 +23,24 @@ x-anchors:
$ref: "#/components/headers/Allowed" $ref: "#/components/headers/Allowed"
'500': '500':
$ref: "#/components/responses/InternalServerError" $ref: "#/components/responses/InternalServerError"
ImageHeaders: &headers-image
<<: *headers-default
Digest:
description: SHA256 hash of the provided image content
schema:
type: string
format: sha256
example: sha256:f2bf647325d5a6ad2d7ca138293f9cb224dd863fde0e3fa46bc5c15b43fece5c
Content-Type:
description: Content type of the image being returned
schema:
type: string
enum: [image/jpeg, image/png]
Cache-Control:
description: Cache settings for the image to prevent unnecessary reloads
schema:
type: string
example: public, max-age=604800, immutable
paths: paths:
/openapi.json: /openapi.json:
get: get:
@ -37,7 +55,43 @@ paths:
application/json: application/json:
schema: schema:
type: object type: object
/image/{image_name}.{format}: /heartbeat:
head:
summary: Check whether the service is online
operationId: Heartbeat
tags: ["meta"]
responses:
'200':
description: Server is operational
headers: *headers-default
'500':
description: Server is not operating correctly
headers: *headers-default
/image/{image_name}:
head:
summary: Returns metadata about the image request
operationId: ImageHead
tags: ["meta"]
parameters:
- $ref: "#/components/parameters/ImageName"
- $ref: "#/components/parameters/ImageFormat"
responses:
'200':
$ref: "#/components/responses/ImageMeta"
'401':
$ref: "#/components/responses/UnauthenticatedError"
'404':
$ref: "#/components/responses/NotFoundError"
'405':
$ref: "#/components/responses/MethodNotAllowedError"
'410':
$ref: "#/components/responses/DeletedError"
'422':
$ref: "#/components/responses/UnacceptableError"
'500':
$ref: "#/components/responses/InternalServerError"
'501':
$ref: "#/components/responses/NotImplementedError"
get: get:
summary: Retrieve the image resource with the specified ID summary: Retrieve the image resource with the specified ID
operationId: ImageGet operationId: ImageGet
@ -48,12 +102,20 @@ paths:
responses: responses:
'200': '200':
$ref: "#/components/responses/Image" $ref: "#/components/responses/Image"
'401':
$ref: "#/components/responses/UnauthenticatedError"
'404': '404':
$ref: "#/components/responses/NotFoundError" $ref: "#/components/responses/NotFoundError"
'405':
$ref: "#/components/responses/MethodNotAllowedError"
'410': '410':
$ref: "#/components/responses/DeletedError" $ref: "#/components/responses/DeletedError"
'422':
$ref: "#/components/responses/UnacceptableError"
'500': '500':
$ref: "#/components/responses/InternalServerError" $ref: "#/components/responses/InternalServerError"
'501':
$ref: "#/components/responses/NotImplementedError"
options: options:
summary: Retrieve available HTTP verbs for the selected endpoint summary: Retrieve available HTTP verbs for the selected endpoint
operationId: ImageOptions operationId: ImageOptions
@ -62,71 +124,11 @@ paths:
- $ref: "#/components/parameters/ImageName" - $ref: "#/components/parameters/ImageName"
- $ref: "#/components/parameters/ImageFormat" - $ref: "#/components/parameters/ImageFormat"
responses: *responses-options responses: *responses-options
/image/{image_name}/{dimension}-{value}.{format}: /image/{image_name}/{alias}:
get: head:
summary: Fetch a scaled image summary: Returns metadata about the image request
operationId: ThumbnailScale operationId: ImageAliasHead
tags: ["manipulate"]
parameters:
- $ref: "#/components/parameters/ImageName"
- $ref: "#/components/parameters/ImageFormat"
- $ref: "#/components/parameters/ImageScaleDimension"
- $ref: "#/components/parameters/ImageScaleValue"
responses:
'200':
$ref: "#/components/responses/Image"
'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"] 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':
$ref: "#/components/responses/Image"
'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
/image/{image_name}/{alias}.{format}:
get:
summary: Fetch a pre configured version of the image
operationId: ImageAlias
tags: ["manipulate"]
parameters: parameters:
- $ref: "#/components/parameters/ImageName" - $ref: "#/components/parameters/ImageName"
- $ref: "#/components/parameters/ImageFormat" - $ref: "#/components/parameters/ImageFormat"
@ -134,10 +136,39 @@ paths:
responses: responses:
'200': '200':
$ref: "#/components/responses/Image" $ref: "#/components/responses/Image"
'401':
$ref: "#/components/responses/UnauthenticatedError"
'404': '404':
$ref: "#/components/responses/NotFoundError" $ref: "#/components/responses/NotFoundError"
'405':
$ref: "#/components/responses/MethodNotAllowedError"
'410': '410':
$ref: "#/components/responses/DeletedError" $ref: "#/components/responses/DeletedError"
'422':
$ref: "#/components/responses/UnacceptableError"
'500':
$ref: "#/components/responses/InternalServerError"
get:
summary: Fetch a pre configured version of the image
operationId: ImageAliasGet
tags: ["image"]
parameters:
- $ref: "#/components/parameters/ImageName"
- $ref: "#/components/parameters/ImageFormat"
- $ref: "#/components/parameters/ImageAlias"
responses:
'200':
$ref: "#/components/responses/Image"
'401':
$ref: "#/components/responses/UnauthenticatedError"
'404':
$ref: "#/components/responses/NotFoundError"
'405':
$ref: "#/components/responses/MethodNotAllowedError"
'410':
$ref: "#/components/responses/DeletedError"
'422':
$ref: "#/components/responses/UnacceptableError"
'500': '500':
$ref: "#/components/responses/InternalServerError" $ref: "#/components/responses/InternalServerError"
options: options:
@ -163,13 +194,14 @@ components:
type: object type: object
example: example:
event_id: 0de388ae-8277-49ba-b225-3ef7f5b9d084 event_id: 0de388ae-8277-49ba-b225-3ef7f5b9d084
message: An error ocurred in a backend component message: Website go brrr
data: {} data: {}
headers: headers:
Version: Version:
description: Keyosk server application version description: ImageMuck server application version
schema: schema:
type: string type: string
example: imagemuck-1.0.0
Allowed: Allowed:
description: Comma delimited list of valid HTTP verbs description: Comma delimited list of valid HTTP verbs
schema: schema:
@ -183,53 +215,14 @@ components:
schema: schema:
type: string type: string
ImageFormat: ImageFormat:
name: format name: Accept
in: path in: header
description: Image format extension description: Content type indicating what format the image should be returned in
required: true required: false
schema: schema:
type: string type: string
enum: [jpg, jpeg, png] default: image/jpeg
ImageScaleDimension: enum: [image/jpeg, image/png]
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
ImageAlias: ImageAlias:
name: alias name: alias
in: path in: path
@ -239,17 +232,14 @@ components:
type: string type: string
responses: responses:
Image: Image:
description: Image content for provided ID description: Image content for the specified ID
headers: headers: *headers-image
<<: *headers-default
Digest:
description: SHA256 hash of the provided image content
schema:
type: string
format: sha256
content: content:
image/jpeg: {} image/jpeg: {}
image/png: {} image/png: {}
ImageMeta:
description: Image content for the specified ID
headers: *headers-image
InternalServerError: InternalServerError:
description: Internal server error description: Internal server error
headers: *headers-default headers: *headers-default
@ -278,3 +268,24 @@ components:
application/json: application/json:
schema: schema:
$ref: "#/components/schemas/Error" $ref: "#/components/schemas/Error"
UnacceptableError:
description: Requested image format is not supported by the server
headers: *headers-default
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
UnauthenticatedError:
description: Resource requires authentication that was not successfully provided
headers: *headers-default
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
NotImplementedError:
description: The server does not support retriving the full resolution image
headers: *headers-default
content:
application/json:
schema:
$ref: "#/components/schemas/Error"