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:
parent
7b49146123
commit
f9c38a5bcc
255
openapi.yaml
255
openapi.yaml
@ -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"
|
||||||
|
Loading…
Reference in New Issue
Block a user