IBX-8947: Add 2 cart REST routes; update Cart examples #2501

adriendupuis · 2024-09-20T13:27:55Z

Question	Answer
JIRA Ticket	IBX-8947
Versions	4.6, master
Edition	All

Add two routes:

/api/ibexa/v2/cart/{identifier}/validate added in ibexa/cart#38 (and asked in IBX-8947)
- Preview: https://ez-systems-developer-documentation--2501.com.readthedocs.build/en/2501/api/rest_api/rest_api_reference/rest_api_reference.html#managing-commerce-carts-cart-validation
/api/ibexa/v2/cart/authorize added in ibexa/cart#80
- Preview: https://ez-systems-developer-documentation--2501.com.readthedocs.build/en/2501/api/rest_api/rest_api_reference/rest_api_reference.html#managing-commerce-carts-cart-authorization

Add XML examples and update JSON examples.

Examples generation

Done with

Commerce 4.6.11
DDEV
ibexa/cart#97
xq

set -x;

host='http://ddev-ibexa-tmp.ddev.site:8080';
baseUri="$host/api/ibexa/v2";
mimeTypePrefix='application/vnd.ibexa.api';
restRefDir='docs/api/rest_api/rest_api_reference';

for format in 'json' 'xml'; do

parser='jq';
if [ 'xml' = "$format" ]; then
  parser='xq';
fi;

curl "$baseUri/cart/authorize" \
  -c anonymous_cookies.txt \
  -X 'POST' \
  -H "Accept: $mimeTypePrefix.Token+$format" \
> $restRefDir/input/examples/cart/authorize/Token.$format.example;
anonymous_token=`cat $restRefDir/input/examples/cart/authorize/Token.$format.example | $parser -r '.Token.value'`;
if [ 'json' = "$format" ]; then
  echo '' >> $restRefDir/input/examples/cart/authorize/Token.$format.example;
fi;

curl "$baseUri/cart" \
  -b anonymous_cookies.txt -H "X-CSRF-Token: $anonymous_token" \
  -H "Content-Type: $mimeTypePrefix.CartCreate+$format" \
  --data "@$restRefDir/input/examples/cart/POST/CartCreate.$format.example" \
  -H "Accept: application/$format" \
> $restRefDir/input/examples/cart/POST/Cart.$format.example;
identifier=`cat $restRefDir/input/examples/cart/POST/Cart.$format.example | $parser -r '.Cart.identifier'`;
if [ 'json' = "$format" ]; then
  echo '' >> $restRefDir/input/examples/cart/POST/Cart.$format.example;
fi;

curl "$baseUri/cart/$identifier" \
  -b anonymous_cookies.txt -H "X-CSRF-Token: $anonymous_token" \
  -H "Accept: $mimeTypePrefix.Cart+$format" \
> $restRefDir/input/examples/cart/identifier/Cart.$format.example;
if [ 'json' = "$format" ]; then
  echo '' >> $restRefDir/input/examples/cart/identifier/Cart.$format.example;
fi;
if [ '' = "$(diff $restRefDir/input/examples/cart/POST/Cart.$format.example $restRefDir/input/examples/cart/identifier/Cart.$format.example)" ]; then
  rm $restRefDir/input/examples/cart/identifier/Cart.$format.example;
fi;

curl "$baseUri/cart/view" \
  -b anonymous_cookies.txt -H "X-CSRF-Token: $anonymous_token" \
  --data "@$restRefDir/input/examples/cart/view/CartViewInput.$format.example" \
  -H "Content-Type: $mimeTypePrefix.CartViewInput+$format" \
  -H "Accept: $mimeTypePrefix.CartView+$format" \
> $restRefDir/input/examples/cart/view/CartView.$format.example;
if [ 'json' = "$format" ]; then
  echo '' >> $restRefDir/input/examples/cart/view/CartView.$format.example;
fi;

curl "$baseUri/cart/$identifier/validate" \
  -b anonymous_cookies.txt -H "X-CSRF-Token: $anonymous_token" \
  -X 'POST' \
  -H "Accept: $mimeTypePrefix.CartConstraintViolationList+$format" \
> $restRefDir/input/examples/cart/identifier/validate/CartConstraintViolationList.$format.example;
if [ 'json' = "$format" ]; then
  echo '' >> $restRefDir/input/examples/cart/identifier/validate/CartConstraintViolationList.$format.example;
fi;

curl "$baseUri/cart/$identifier" \
  -b anonymous_cookies.txt -H "X-CSRF-Token: $anonymous_token" \
  -X 'DELETE' \
;

rm anonymous_cookies.txt;

done;
exit 0;

Checklist

Text renders correctly
Text has been checked with vale
Description metadata is up to date
Redirects cover removed/moved pages
Code samples are working
PHP code samples have been fixed with PHP CS fixer
Added link to this PR in relevant JIRA ticket or code PR

/api/ibexa/v2/cart/{identifier}/validate /api/ibexa/v2/cart/authorize

adriendupuis · 2024-09-26T09:52:05Z

docs/api/rest_api/rest_api_reference/input/examples/cart/POST/CartCreate.xml.example

I'm not able to find a way to add a context like JSON does.

<CartCreate> <name>Default</name> <currencyCode>EUR</currencyCode> <context> <foo>bar</foo> </context> </CartCreate>

?xml version="1.0" encoding="UTF-8"?> <ErrorMessage media-type="application/vnd.ibexa.api.ErrorMessage+xml"> <errorCode>500</errorCode> <errorMessage>Internal Server Error</errorMessage> <errorDescription>Array to string conversion</errorDescription> <trace>…</trace> <file>/var/www/html/vendor/ibexa/rest/src/lib/Output/Generator/Xml.php</file> <line>169</line> </ErrorMessage>

adriendupuis · 2024-09-26T10:14:34Z

...i_reference/input/examples/cart/identifier/validate/CartConstraintViolationList.json.example

+{
+    "CartConstraintViolationList": {
+        "_media-type": "application\/vnd.ibexa.api.CartConstraintViolationList+json",
+        "violations": []


I didn't manage to insert invalid data on purpose.

I tried to add a product with no stock, it's added without any error. I thought https://github.com/ibexa/cart/blob/main/src/lib/Validation/Constraint/ProductAvailableValidator.php would complain, but no. On the storefront, the product is indicated as Out of stock but if I edit the HTML and remove the disabled attribute from the "Add to cart" button, I can add it to the cart without error. It seems there is no product availability around there.

I tried to add a product/entry called 'test' to match the example without having configuring proper TVA for the region.

curl "$baseUri/cart/$identifier/entry" \ -b anonymous_cookies.txt -H "X-CSRF-Token: $anonymous_token" \ -H "Content-Type: $mimeTypePrefix.CartEntryAdd+$format" \ --data "@$restRefDir/input/examples/cart/entry/POST/CartEntryAdd.json.example" \ ;

The cart is validated on the fly and I get the following error:

<?xml version="1.0" encoding="UTF-8"?> <ErrorMessage media-type="application/vnd.ibexa.api.ErrorMessage+xml"> <errorCode>406</errorCode> <errorMessage>Not Acceptable</errorMessage> <errorDescription>Argument '$entryAddStruct' is invalid: Product "test" has no VAT Category set.</errorDescription> <trace>…</trace> <file>/var/www/html/vendor/ibexa/cart/src/lib/Service/CartService.php</file> <line>239</line> </ErrorMessage>

I tried to fix the error and reintroduce it later but fail. I had error 500 on every page of the DXP for a region VAT not found.

I stopped my test there.

docs/api/rest_api/rest_api_reference/input/ibexa-types.raml

adriendupuis · 2024-09-26T14:41:17Z

docs/api/rest_api/rest_api_reference/input/ibexa-types.raml

+    properties:
+        violations:
+            type: array
+            items: CartConstraintViolation


Maybe a CartConstraintViolationWrapper is needed but I didn't manage to product constraint violation to study it.

mnocon

Thanks! The script to generate the responses was definitely useful - especially once I got the right xq executable 😄 (https://github.com/mikefarah/yq worked)

mnocon · 2024-11-27T22:05:00Z

docs/api/rest_api/rest_api_reference/input/examples/cart/POST/Cart.json.example

-        "_media-type": "application/vnd.ibexa.api.Cart+json",
-        "id": 12,
-        "identifier": "fafccc4b-cce1-40d7-8d23-29ad41638581",
+        "_media-type": "application\/vnd.ibexa.api.Cart+json",


Question: should the slashes be escaped?

I see we sometimes do it and sometimes don't, does it matter?

Examples:
https://github.com/ibexa/documentation-developer/blob/master/docs/api/rest_api/rest_api_reference/input/examples/shipping/methods/identifier/GET/ShippingMethod.json.example#L3
https://github.com/ibexa/documentation-developer/blob/master/docs/api/rest_api/rest_api_reference/input/examples/content/locations/path/GET/Location.json.example#L3

Or maybe it doesn't matter?

@mnocon

I checked on https://www.json.org/json-en.html and further on https://ecma-international.org/publications-and-standards/standards/ecma-404/. The standard's PDF states:

All code points may
be placed within the quotation marks except for the code points that must be escaped: quotation mark
(U+0022), reverse solidus (U+005C), and the control characters U+0000 to U+001F.
[…]
\/ represents the solidus character (U+002F).

So escaping the slash (a.k.a solidus) is optional; it doesn't matter.

% echo '{ "slash": "\/" }' | jq { "slash": "/" }

jq understands it but considers it's not worth keeping it.

We could status for consistency and open a new PR about this. I would vote for removing them all.

docs/api/rest_api/rest_api_reference/input/ibexa-cart.raml

Co-authored-by: Marek Nocoń <mnocon@users.noreply.github.com>

/api/ibexa/v2/cart/{identifier}/validate /api/ibexa/v2/cart/authorize --------- Co-authored-by: Marek Nocoń <mnocon@users.noreply.github.com> (cherry picked from commit 50b28fb)

adriendupuis added 2 commits September 20, 2024 15:14

Draft missing cart REST routes

90ad68d

/api/ibexa/v2/cart/{identifier}/validate /api/ibexa/v2/cart/authorize

Fix PATCH /cart/{identifier} modified by mistake

6dbb666

adriendupuis changed the title ~~Add missing cart REST routes~~ IBX-8947: Add missing cart REST routes Sep 25, 2024

adriendupuis added 6 commits September 25, 2024 09:31

Merge branch 'master' into update-cart-rest

8063a6a

ibexa-types.raml: Draft CartConstraintViolation types

46a9062

Continue /cart/authorize route doc

a54aeb8

Update Cart examples

23252bd

Update Cart examples

8e3c909

REST API Ref: generate HTML

dd25f24

adriendupuis changed the title ~~IBX-8947: Add missing cart REST routes~~ IBX-8947: Add 2 cart REST routes; update Cart examples Sep 26, 2024

adriendupuis commented Sep 26, 2024

View reviewed changes

docs/api/rest_api/rest_api_reference/input/ibexa-types.raml Outdated Show resolved Hide resolved

Update docs/api/rest_api/rest_api_reference/input/ibexa-types.raml

ab81f32

adriendupuis commented Sep 26, 2024

View reviewed changes

adriendupuis added the Needs DEV review label Sep 26, 2024

adriendupuis requested review from tischsoic and bdunogier September 26, 2024 14:43

adriendupuis marked this pull request as ready for review September 27, 2024 14:20

adriendupuis requested a review from konradoboza November 27, 2024 13:24

konradoboza approved these changes Nov 27, 2024

View reviewed changes

adriendupuis added Needs DOC review and removed Needs DEV review labels Nov 27, 2024

mnocon approved these changes Nov 27, 2024

View reviewed changes

adriendupuis and others added 2 commits December 3, 2024 13:12

Update docs/api/rest_api/rest_api_reference/input/ibexa-cart.raml

e33db33

Co-authored-by: Marek Nocoń <mnocon@users.noreply.github.com>

Merge branch 'master' into update-cart-rest

bbf0966

adriendupuis added Ready for MERGE and removed Needs DOC review labels Dec 3, 2024

REST API Ref: generate HTML

84b1795

adriendupuis merged commit 50b28fb into master Dec 3, 2024
5 of 6 checks passed

adriendupuis deleted the update-cart-rest branch December 3, 2024 13:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

IBX-8947: Add 2 cart REST routes; update Cart examples #2501

IBX-8947: Add 2 cart REST routes; update Cart examples #2501

adriendupuis commented Sep 20, 2024 •

edited

Loading

adriendupuis Sep 26, 2024

adriendupuis Sep 26, 2024 •

edited

Loading

adriendupuis Sep 26, 2024

mnocon left a comment

mnocon Nov 27, 2024

adriendupuis Dec 3, 2024 •

edited

Loading

IBX-8947: Add 2 cart REST routes; update Cart examples #2501

IBX-8947: Add 2 cart REST routes; update Cart examples #2501

Conversation

adriendupuis commented Sep 20, 2024 • edited Loading

Examples generation

Checklist

adriendupuis Sep 26, 2024

Choose a reason for hiding this comment

adriendupuis Sep 26, 2024 • edited Loading

Choose a reason for hiding this comment

adriendupuis Sep 26, 2024

Choose a reason for hiding this comment

mnocon left a comment

Choose a reason for hiding this comment

mnocon Nov 27, 2024

Choose a reason for hiding this comment

adriendupuis Dec 3, 2024 • edited Loading

Choose a reason for hiding this comment

adriendupuis commented Sep 20, 2024 •

edited

Loading

adriendupuis Sep 26, 2024 •

edited

Loading

adriendupuis Dec 3, 2024 •

edited

Loading