diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 0000000..aa9380c --- /dev/null +++ b/openapi.yaml @@ -0,0 +1,218 @@ +--- +openapi: "3.0.2" +info: + version: 0.1.0 + title: ImageMonk + description: >- + ImageMonk is a simple HTTP server that allows users to upload + images and retrieve them at a later time. In addition, it + supports generating (and caching) scaled versions of the + uploaded images for use as thumbnails. + license: + name: MIT + url: https://mit-license.org/ +x-anchors: + DefaultHeaders: &headers-default + x-imagemonk-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/: + put: + summary: Upload an image to the server + operationId: ImageUpload + tags: ["image"] + responses: + '201': + description: Image uploaded successfully + '406': + description: Image is not acceptable for upload + headers: *headers-default + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + '500': + $ref: "#/components/responses/InternalServerError" + options: + summary: Retrieve available HTTP verbs for the selected endpoint + operationId: ImageUploadOptions + tags: ["meta"] + responses: *responses-options + /image/{image_id}.jpeg: + get: + summary: Retrieve the image resource with the specified ID + operationId: ImageGet + tags: ["image"] + parameters: + - $ref: "#/components/parameters/ImageUUID" + responses: + '200': + description: Image content for provided ID + headers: *headers-default + content: + image/jpeg: {} + '404': + $ref: "#/components/responses/NotFoundError" + '410': + $ref: "#/components/responses/DeletedError" + '500': + $ref: "#/components/responses/InternalServerError" + delete: + summary: Delete an image from the server + operationId: ImageDelete + tags: ["image"] + parameters: + - $ref: "#/components/parameters/ImageUUID" + responses: + '204': + description: Image with provided ID successfully deleted + headers: *headers-default + '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: ImageOptions + tags: ["meta"] + parameters: + - $ref: "#/components/parameters/ImageUUID" + responses: *responses-options + /thumb/{image_id}/scale/{scale_width}.jpeg: + get: + summary: Fetch a scaled thumbnail image + operationId: ThumbnailScale + tags: ["thumbnail"] + parameters: + - $ref: "#/components/parameters/ImageUUID" + - name: scale_width + in: path + description: Width in pixels to scale the image to + required: true + schema: + type: number + format: integer + responses: + '200': + description: Scaled image thumbnail content + headers: *headers-default + content: + image/jpeg: {} + '404': + $ref: "#/components/responses/NotFoundError" + '410': + $ref: "#/components/responses/DeletedError" + '500': + $ref: "#/components/responses/InternalServerError" + /thumb/{image_id}/size/{width}x{height}.jpeg: + get: + summary: Fetch a thumbnail image with specific dimensions + operationId: ThumbnailDimension + tags: ["thumbnail"] + parameters: + - $ref: "#/components/parameters/ImageUUID" + - name: width + in: path + description: Width in pixels of the image thumbnail + required: true + schema: + type: number + format: integer + - name: height + in: path + description: Height in pixels of the image thumbnail + required: true + schema: + type: number + format: integer + responses: + '200': + description: Scaled thumbnail image of specified dimentions + headers: *headers-default + content: + image/jpeg: {} + '404': + $ref: "#/components/responses/NotFoundError" + '410': + $ref: "#/components/responses/DeletedError" + '500': + $ref: "#/components/responses/InternalServerError" +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: + ImageUUID: + name: image_id + in: path + description: Image resource UUID + required: true + schema: + type: string + format: uuid + 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" + DeletedError: + description: Image with provided ID was deleted + headers: *headers-default + content: + application/json: + schema: + $ref: "#/components/schemas/Error"