HTM/ovpay
4
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases 1 Wiki Activity

Process feedback

Browse Source 
Remove 403 error description, add 404 example in correct RFC9457 format, refactor example labels, remove non-occurring errors
This commit is contained in:
Max Martens 2025-02-10 17:05:40 +01:00
parent 5ef6777aad
commit 5fab4e8dcc
1 changed files with 50 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
src/openapi/products/SE-products.yaml
View File

@ -50,7 +50,7 @@ paths:
{ {
"Entries": [] "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) 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 description: Only two sellingPeriods for touchpoint 1 and/or 2 (part of same retailer) are returned - the price for touchpointId 1 is returned
value: 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) 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 description: Only two sellingPeriods for touchpoint 3 and/or 4 (part of same retailer) are returned - the price for touchpointId 3 is returned
value: 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) 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. 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: value:
@ -148,7 +148,7 @@ paths:
} }
] ]
} }
getListMultipleProductsTouchpointId3: List containing multiple products (called by touchpointId 3):
summary: 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 description: Only products that have active SellingPeriods for touchpoint 3 and/or 4 (part of same retailer) are returned
value: 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}: /products/{productId}:
get: get:
tags: tags:
@ -242,16 +218,18 @@ paths:
summary: Get more details for a single HTM product (including all child products), specified by the productId summary: Get more details for a single HTM product (including all child products), specified by the productId
description: |- description: |-
Get more details for a single HTM product (including all child products/productVariants), specified by the productId. \ 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 active selling periods and prices for the calling touchpoint are returned. Future/past prices and prices
for other touchpoints are thus filtered out. 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 Touchpoints can only retrieve details for products that they are allowed to see and/or sell at the time of the request
`sellableTouchPointIds` array in the products list response). A touchpoint can determine its own touchpointId by checking the `X-HTM-TOUCHPOINT-ID-HEADER` HTTP header. (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 a touchpoint tries to retrieve details for a product that it is not allowed to sell, a 403 error is thrown.
When no product exists for the given productId, a 404 Error response is returned.
parameters: parameters:
- name: productId - name: productId
in: path in: path
@ -269,7 +247,7 @@ paths:
schema: schema:
$ref: '#/components/schemas/ProductPayloadResponse' $ref: '#/components/schemas/ProductPayloadResponse'
examples: examples:
getDetails90DiscountPilotProductTouchpointId3: 90% Discount F&F pilot product (called by touchpointId 3):
summary: 90% Discount F&F pilot product (called by touchpointId 3) summary: 90% Discount F&F pilot product (called by touchpointId 3)
description: |- description: |-
All details (that the calling touchpoint is allowed to see) for the 90% Discount F&F pilot product.\ 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, "purchasePrices": null,
"productVariants": null "productVariants": null
} }
getDetails20DiscountPilotProductTouchpointId3: 20% Discount product (called by touchpointId 4):
summary: 20% Discount product (called by touchpointId 4) summary: 20% Discount product (called by touchpointId 4)
description: |- description: |-
All details (that the calling touchpoint is allowed to see) for the 20% Discount product.\ 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) summary: Regio Vrij product and (part of) its productVariants (called by touchpointId 3)
description: |- description: |-
All details (that the calling touchpoint is allowed to see) for the parent Regio Vrij product 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': '404':
description: '404' description: '404'
content: content:
application/json: application/json:
schema: schema:
$ref: '#/components/schemas/404Response' $ref: '#/components/schemas/rfc9457Response'
'500': examples:
description: '500' Non-existing productId:
content: summary: Non-existing productId
application/json: value:
schema: {
$ref: '#/components/schemas/500Response' "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: components:
schemas: schemas:
TaxMetadataResponse: TaxMetadataResponse:
@ -2524,91 +2485,34 @@ components:
type: string type: string
format: date-time-offset format: date-time-offset
example: '2024-09-03T10:01:34.000+00:00' example: '2024-09-03T10:01:34.000+00:00'
400Response: rfc9457Response:
type: object type: object
properties: properties:
code:
type: string
example: '400'
type: type:
type: string type: string
message: format: url
example: "https://www.htm.nl/api/v1/rfc9457Error"
title:
type: string type: string
example: Bad Request description: "Short summary of the error."
description: example: "The request is not valid."
detail:
type: string type: string
example: '''2023-02-01 00:00:00'' is not a valid Datetime' description: "More detailed descriptionof the error."
apiErrorCode: example: "Some required parameters are missing."
instance:
type: string type: string
example: htm.api.err.40xxx description: "Unique identifier to correlate this specific error with logging in other applications."
401Response: example: "urn:uuid:13c8416f-7632-4c8b-8a16-2132197be60c"
type: object additionalProperty1:
properties:
code:
type: string type: string
example: '401' description: "Example of an additional property value to be used for error reporting."
type: example: "additionalValue1"
type: string additionalProperty2:
message: type: array
type: string description: "Example of an additional property array to be used for error reporting."
example: Invalid Credentials items:
description: type: string
type: string example:
example: >- - "additionalValue2-1"
Invalid Credentials. Make sure you have provided the correct - "additionalValue2-2"
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