From 769ca89be209e5a925d6665fdf24538fa6c0e348 Mon Sep 17 00:00:00 2001 From: bglamadrid Date: Thu, 25 Jul 2024 16:39:59 -0400 Subject: [PATCH] chore!: replace error response schemas - add new object schema `AppError` - add new response schema `Error`, referencing `AppError` as response body - replace response schemas with `Error` - `GET /access 403` - `GET /access/{resource} 403` - `GET /data/people 403` - `PUT /data/products 400,403,404` - `POST /data/products 400,403` - `PATCH /data/products 400,403,404` - `DELETE /data/products 403,404` - `GET /data/orders 403` - `PUT /data/orders 400,403,404` - `PUT /data/orders 400,403,404` - `POST /data/orders 400,403` - `PATCH /data/orders 400,403,404` - `DELETE /data/orders 403,404` - `POST /data/orders/confirmation 403` - `POST /data/orders/rejection 403` - `POST /data/orders/completion 403` - `GET /data/users 403` - `PUT /data/users 400,403,404` - `POST /data/users 400,403` - `PATCH /data/users 400,403,404` - `DELETE /data/users 403,404` - `GET /data/images 403` - `PUT /data/images 400,403,404` - `POST /data/images 400,403` - `PATCH /data/images 400,403,404` - `DELETE /data/images 403,404` - `GET /data/user_roles 403` - `POST /public/checkout 400,403` - `POST /public/checkout/validate 400,404` - `POST /public/receipt/{code} 404` - `GET /data/product_categories 403` - `PUT /data/product_categories 400,403,404` - `POST /data/product_categories 400,403` - `PATCH /data/product_categories 400,403,404` - `DELETE /data/product_categories 403,404` - `GET /account/profile 403` - `PUT /account/resource 400,403` - `POST /public/register 400` - `PUT /data/shippers 400,403,404` - `POST /data/shippers 400,403` - `PATCH /data/shippers 400,403,404` - `DELETE /data/shippers 403,404` - `PUT /data/product_lists 400,403,404` - `POST /data/product_lists 400,403` - `PATCH /data/product_lists 400,403,404` - `DELETE /data/product_lists 403,404` - `PUT /data/product_list_contents 400,403,404` - `POST /data/product_list_contents 400,403` - `DELETE /data/product_list_contents 403,404` - remove now-unused response schemas - `Forbidden` - `NotFound` - `BadRequestBody` - increment patch version this is yet another breaking change, but no new release is out yet --- src/trebol-api.json | 232 ++++++++++++++++++++++++-------------------- 1 file changed, 127 insertions(+), 105 deletions(-) diff --git a/src/trebol-api.json b/src/trebol-api.json index 77eda4a..1c7cf1a 100644 --- a/src/trebol-api.json +++ b/src/trebol-api.json @@ -2,7 +2,7 @@ "openapi": "3.0.1", "info": { "title": "Trébol eCommerce API", - "version": "2.0.1", + "version": "2.0.2", "description": "A collection of resources that the Trébol backend exposes to interact with. Depends on, and references `Trébol eCommerce API Commons v1.0.0`", "contact": { "name": "Benjamin La Madrid", @@ -94,7 +94,7 @@ "$ref": "#/components/responses/AuthorizedAccessToRoutes" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -135,7 +135,7 @@ "$ref": "#/components/responses/AuthorizedAccessToResource" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -226,7 +226,7 @@ "$ref": "#/components/responses/PaginatedCollection" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -331,13 +331,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -369,10 +369,10 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -404,13 +404,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -432,10 +432,10 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -601,7 +601,7 @@ "$ref": "#/components/responses/PaginatedCollection" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -633,13 +633,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -671,10 +671,10 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -706,13 +706,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -734,10 +734,10 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -795,7 +795,7 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -843,7 +843,7 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -891,7 +891,7 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -973,7 +973,7 @@ "$ref": "#/components/responses/PaginatedCollection" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1005,13 +1005,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1043,10 +1043,10 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1078,13 +1078,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1106,10 +1106,10 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1219,7 +1219,7 @@ "$ref": "#/components/responses/PaginatedCollection" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1251,13 +1251,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1289,10 +1289,10 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1324,13 +1324,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1352,10 +1352,10 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1407,7 +1407,7 @@ } }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1526,10 +1526,10 @@ "description": "Normal response. The transaction was acknowledged and initiated. Details to redirect towards the payment page are included." }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1569,10 +1569,10 @@ "description": "Normal, empty response, sent when the transaction was approved. Redirects the user.\n\n'Location' response header should be included with a URL to the result page." }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1617,7 +1617,7 @@ } }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1705,13 +1705,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1743,10 +1743,10 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1778,13 +1778,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1806,10 +1806,10 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1893,7 +1893,7 @@ } }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -1925,10 +1925,10 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2077,7 +2077,7 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2233,13 +2233,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2271,10 +2271,10 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2306,13 +2306,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2334,10 +2334,10 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2502,13 +2502,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2540,10 +2540,10 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2575,13 +2575,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2603,10 +2603,10 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2764,13 +2764,13 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2802,10 +2802,10 @@ "$ref": "#/components/responses/Empty" }, "400": { - "$ref": "#/components/responses/BadRequestBody" + "$ref": "#/components/responses/Error" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -2853,10 +2853,10 @@ "$ref": "#/components/responses/Empty" }, "403": { - "$ref": "#/components/responses/Forbidden" + "$ref": "#/components/responses/Error" }, "404": { - "$ref": "#/components/responses/NotFound" + "$ref": "#/components/responses/Error" } }, "security": [ @@ -3763,6 +3763,27 @@ "totalCount": 32, "pageSize": 15 } + }, + "AppError": { + "type": "object", + "properties": { + "code": { + "description": "Unique code of the error", + "type": "string" + }, + "message": { + "description": "A brief, human-readable description of the error", + "type": "string" + }, + "detailMessage": { + "description": "A more technical, in-depth description of the error", + "type": "string" + }, + "canRetry": { + "description": "Whether or not the client may retry the request that originated the error", + "type": "boolean" + } + } } }, "responses": { @@ -3776,8 +3797,15 @@ }, "description": "Normal response for most \"/data\" methods; sends items in an array, along with pagination metadata." }, - "Forbidden": { - "description": "Erroneous, empty response for requests not meeting security requirements. Most likely, it does not have authorization to access specific privileged resource(s), or does not include any form of authentication while requesting some privileged resource(s)." + "Error": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AppError" + } + } + }, + "description": "Standard response for unsuccessful requests; can include an explanation and may (or may not) be retried thereafter." }, "AuthorizedAccessToResource": { "content": { @@ -3799,9 +3827,6 @@ }, "description": "Normal response. Sends an array of API routes available for use from a parent path." }, - "NotFound": { - "description": "Non-erroneous, empty response which indicates that no data matched the provided criteria." - }, "Empty": { "description": "Normal response which indicates everything went right (after successfully altering data, for example) and that there's no additional information to be included." }, @@ -3816,9 +3841,6 @@ }, "AllowMethodGET-PUT": { "description": "Normal, empty response to some OPTIONS requests. Should include CORS headers and indicate that only the GET and PUT methods are allowed." - }, - "BadRequestBody": { - "description": "Erroneous response, sent when the request does not meet certain expectations. This probably because required properties were not included in the request body, or because certain data constraints (duplicate code numbers, for example) were not met." } }, "securitySchemes": {