From 5fab4e8dcc2b5efac2154709c90a8e06ff892a6b Mon Sep 17 00:00:00 2001 From: Max Martens Date: Mon, 10 Feb 2025 17:05:40 +0100 Subject: [PATCH] Process feedback Remove 403 error description, add 404 example in correct RFC9457 format, refactor example labels, remove non-occurring errors --- src/openapi/products/SE-products.yaml | 196 +++++++------------------- 1 file changed, 50 insertions(+), 146 deletions(-) diff --git a/src/openapi/products/SE-products.yaml b/src/openapi/products/SE-products.yaml index b5eb4f7..0353d89 100644 --- a/src/openapi/products/SE-products.yaml +++ b/src/openapi/products/SE-products.yaml @@ -50,7 +50,7 @@ paths: { "Entries": [] } - getListOneProductTouchpointId1: + List containing one product with 4 currently active SellingPeriods (called by touchpointId 1): summary: List containing one product with 4 currently active SellingPeriods (called by touchpointId 1) description: Only two sellingPeriods for touchpoint 1 and/or 2 (part of same retailer) are returned - the price for touchpointId 1 is returned value: @@ -83,7 +83,7 @@ paths: } ] } - getListOneProductTouchpointId3: + List containing one product with 4 currently active SellingPeriods (called by touchpointId 3): summary: List containing one product with 4 currently active SellingPeriods (called by touchpointId 3) description: Only two sellingPeriods for touchpoint 3 and/or 4 (part of same retailer) are returned - the price for touchpointId 3 is returned value: @@ -116,7 +116,7 @@ paths: } ] } - getListOneProductNoPriceTouchpointId3: + List containing one product which can only be sold by touchpointId 3 (called by touchpointId 4): summary: List containing one product which can only be sold by touchpointId 3 (called by touchpointId 4) description: Product is still returned (because touchpointId 3 is part of same retailer) but no price, as touchpointId 4 is not allowed to sell this product. value: @@ -148,7 +148,7 @@ paths: } ] } - getListMultipleProductsTouchpointId3: + List containing multiple products (called by touchpointId 3): summary: List containing multiple products (called by touchpointId 3) description: Only products that have active SellingPeriods for touchpoint 3 and/or 4 (part of same retailer) are returned value: @@ -211,30 +211,6 @@ paths: } ] } - '400': - description: '400' - content: - application/json: - schema: - $ref: '#/components/schemas/400Response' - '401': - description: '401' - content: - application/json: - schema: - $ref: '#/components/schemas/401Response' - '404': - description: '404' - content: - application/json: - schema: - $ref: '#/components/schemas/404Response' - '500': - description: '500' - content: - application/json: - schema: - $ref: '#/components/schemas/500Response' /products/{productId}: get: tags: @@ -242,16 +218,18 @@ paths: summary: Get more details for a single HTM product (including all child products), specified by the productId description: |- Get more details for a single HTM product (including all child products/productVariants), specified by the productId. \ - Only information that is allowed to be seen by the calling touchpoint is returned; i.e. only currently + Only information that is allowed to be seen by the calling touchpoint is returned - i.e. only currently active selling periods and prices for the calling touchpoint are returned. Future/past prices and prices for other touchpoints are thus filtered out. - The response contains the full product tree, including all child products (`productVariants`) of the given productId. + The response contains a product tree, including all child products (`productVariants`) of the given + productId that the touchpoint is allowed to see and/or sell. - Touchpoints can only retrieve details for products that they are allowed to SELL at the time of the request (i.e. its touchpointId is included in the - `sellableTouchPointIds` array in the products list response). A touchpoint can determine its own touchpointId by checking the `X-HTM-TOUCHPOINT-ID-HEADER` HTTP header. - - When a touchpoint tries to retrieve details for a product that it is not allowed to sell, a 403 error is thrown. + Touchpoints can only retrieve details for products that they are allowed to see and/or sell at the time of the request + (i.e. the product is returned in the products list response). + Thus, productVariants that are not available to the calling touchpoint are not returned in the response. + + When no product exists for the given productId, a 404 Error response is returned. parameters: - name: productId in: path @@ -269,7 +247,7 @@ paths: schema: $ref: '#/components/schemas/ProductPayloadResponse' examples: - getDetails90DiscountPilotProductTouchpointId3: + 90% Discount F&F pilot product (called by touchpointId 3): summary: 90% Discount F&F pilot product (called by touchpointId 3) description: |- All details (that the calling touchpoint is allowed to see) for the 90% Discount F&F pilot product.\ @@ -402,7 +380,7 @@ paths: "purchasePrices": null, "productVariants": null } - getDetails20DiscountPilotProductTouchpointId3: + 20% Discount product (called by touchpointId 4): summary: 20% Discount product (called by touchpointId 4) description: |- All details (that the calling touchpoint is allowed to see) for the 20% Discount product.\ @@ -774,7 +752,7 @@ paths: } ] } - getDetailsTreeRegioVrijTouchpointId3: + Regio Vrij product and (part of) its productVariants (called by touchpointId 3): summary: Regio Vrij product and (part of) its productVariants (called by touchpointId 3) description: |- All details (that the calling touchpoint is allowed to see) for the parent Regio Vrij product @@ -1854,40 +1832,23 @@ paths: } ] } - '401': - description: '401' - content: - application/json: - schema: - $ref: '#/components/schemas/401Response' - '403': - description: '403' - content: - application/json: - schema: - $ref: '#/components/schemas/403Response' - examples: - Not allowed to see product details: - summary: Not allowed to see product details - value: - { - "code": "403", - "type": "Forbidden", - "message": "Touchpoint not authorized to see product details", - "description": "The touchpoint is currently not allowed to sell this product and thus can not see its details" - } '404': description: '404' content: application/json: schema: - $ref: '#/components/schemas/404Response' - '500': - description: '500' - content: - application/json: - schema: - $ref: '#/components/schemas/500Response' + $ref: '#/components/schemas/rfc9457Response' + examples: + Non-existing productId: + summary: Non-existing productId + value: + { + "type": "https://www.htm.nl/api/v1/404Error", + "title": "Product not found.", + "detail": "No product found for productId: 1000.", + "instance": "urn:uuid:13c8416f-7632-4c8b-8a16-2132197be60c", + "apiErrorCode": "htm.api.err.404.2" + } components: schemas: TaxMetadataResponse: @@ -2524,91 +2485,34 @@ components: type: string format: date-time-offset example: '2024-09-03T10:01:34.000+00:00' - 400Response: + rfc9457Response: type: object properties: - code: - type: string - example: '400' type: type: string - message: + format: url + example: "https://www.htm.nl/api/v1/rfc9457Error" + title: type: string - example: Bad Request - description: + description: "Short summary of the error." + example: "The request is not valid." + detail: type: string - example: '''2023-02-01 00:00:00'' is not a valid Datetime' - apiErrorCode: + description: "More detailed descriptionof the error." + example: "Some required parameters are missing." + instance: type: string - example: htm.api.err.40xxx - 401Response: - type: object - properties: - code: + description: "Unique identifier to correlate this specific error with logging in other applications." + example: "urn:uuid:13c8416f-7632-4c8b-8a16-2132197be60c" + additionalProperty1: type: string - example: '401' - type: - type: string - message: - type: string - example: Invalid Credentials - description: - type: string - example: >- - Invalid Credentials. Make sure you have provided the correct - security credentials - apiErrorCode: - type: string - example: htm.api.err.40xxx - 403Response: - type: object - properties: - code: - type: string - example: '403' - type: - type: string - example: "Forbidden" - message: - type: string - example: Touchpoint not authorized to see product details - description: - type: string - example: The touchpoint is currently not allowed to sell this product and thus can not see its details - apiErrorCode: - type: string - example: htm.api.err.40xxx - 404Response: - type: object - properties: - code: - type: string - example: '404' - type: - type: string - example: Status report - message: - type: string - example: Not Found - description: - type: string - example: The requested resource is not available. - apiErrorCode: - type: string - example: htm.api.err.40xxx - 500Response: - type: object - properties: - code: - type: string - example: '500' - type: - type: string - message: - type: string - example: Internal Server Error - description: - type: string - apiErrorCode: - type: string - example: htm.api.err.40xxx + description: "Example of an additional property value to be used for error reporting." + example: "additionalValue1" + additionalProperty2: + type: array + description: "Example of an additional property array to be used for error reporting." + items: + type: string + example: + - "additionalValue2-1" + - "additionalValue2-2" \ No newline at end of file