From f9c38a5bcce4ba88a39535d4982e5745e5d76703 Mon Sep 17 00:00:00 2001 From: Ethan Paul <24588726+enpaul@users.noreply.github.com> Date: Thu, 28 Oct 2021 18:33:41 -0400 Subject: [PATCH] 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 --- openapi.yaml | 255 +++++++++++++++++++++++++++------------------------ 1 file changed, 133 insertions(+), 122 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 6eaac3f..60452ac 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -5,7 +5,7 @@ info: 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 + service for autogenerating website-ready banner and preview images from full-size source images. The generated images are automatically cached with deterministic URLs. license: @@ -13,7 +13,7 @@ info: url: https://mit-license.org/ x-anchors: DefaultHeaders: &headers-default - x-imagemuck-version: + Server: $ref: "#/components/headers/Version" OptionsResponses: &responses-options '204': @@ -23,6 +23,24 @@ x-anchors: $ref: "#/components/headers/Allowed" '500': $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: /openapi.json: get: @@ -37,7 +55,43 @@ paths: application/json: schema: 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: summary: Retrieve the image resource with the specified ID operationId: ImageGet @@ -48,12 +102,20 @@ paths: 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': $ref: "#/components/responses/InternalServerError" + '501': + $ref: "#/components/responses/NotImplementedError" options: summary: Retrieve available HTTP verbs for the selected endpoint operationId: ImageOptions @@ -62,71 +124,11 @@ paths: - $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': - $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 + /image/{image_name}/{alias}: + head: + summary: Returns metadata about the image request + operationId: ImageAliasHead 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: - $ref: "#/components/parameters/ImageName" - $ref: "#/components/parameters/ImageFormat" @@ -134,10 +136,39 @@ paths: 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': + $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': $ref: "#/components/responses/InternalServerError" options: @@ -163,13 +194,14 @@ components: type: object example: event_id: 0de388ae-8277-49ba-b225-3ef7f5b9d084 - message: An error ocurred in a backend component + message: Website go brrr data: {} headers: Version: - description: Keyosk server application version + description: ImageMuck server application version schema: type: string + example: imagemuck-1.0.0 Allowed: description: Comma delimited list of valid HTTP verbs schema: @@ -183,53 +215,14 @@ components: schema: type: string ImageFormat: - name: format - in: path - description: Image format extension - required: true + name: Accept + in: header + description: Content type indicating what format the image should be returned in + required: false 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 + default: image/jpeg + enum: [image/jpeg, image/png] ImageAlias: name: alias in: path @@ -239,17 +232,14 @@ components: type: string responses: Image: - description: Image content for provided ID - headers: - <<: *headers-default - Digest: - description: SHA256 hash of the provided image content - schema: - type: string - format: sha256 + description: Image content for the specified ID + headers: *headers-image content: image/jpeg: {} image/png: {} + ImageMeta: + description: Image content for the specified ID + headers: *headers-image InternalServerError: description: Internal server error headers: *headers-default @@ -278,3 +268,24 @@ components: application/json: schema: $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"