...
For detailed documentation on interfaces provided by REST API please refer to swagger spec
Platform
versions take a SaaS API approach whereby sales channel is specified using X-SALES-CHANNEL header thus removing the need for having specific domain names. Label Body 3.7.0+
Each API request has an optional authentication token to correlate with customer virtual session. In versions up to
it was accomplished using yc header, in Label Body 3.6.x
this header is renamed to X-CW-TOKEN. Label Body 3.7.0+
CORS support has been introduced in
and is achieved through sales channel configuration attribute SHOP_CORS_ALLOWED_ORIGINS which is a CSV of Allowed origins verified against the Origin header in the CORS request. Label Body 3.7.0+
Hands on
We recommend reviewing REST API basics cookbook to get more insight on using these interfaces, however please refer to the latest swagger spec for the most up to date API definitions and capabilities.
Figure 1 and 2 below show example of search JSON and XML responses. Note that it is possible can to mix and match body content type as demonstrated in figure 2 with request made as JSON but response received as XML.
Figure 1: Example search call using JSON mode
...
Figure 2: Example search call using JSON request mode and XML response mode
CORS
Label | ||
---|---|---|
|
In order to enable CORS go to shop attributes, find SHOP_CORS_ALLOWED_ORIGINS configuration and define CSV list of allowed origins that are required.
Warning |
---|
Do not adde leading or trailing spaces in this CSV. Correct: "https://demo.yes-cart.org,https://localhost:8081,https://localhost:5555" Incorrect: " https://demo.yes-cart.org,https://localhost:8081 , https://localhost:5555" |
Tip |
---|
If you are setting up your own |
You can test your CORS configuration using cURL, for example:
Code Block | ||||
---|---|---|---|---|
| ||||
# Options request which lists methods and headers for retrieving cart
curl -v -X OPTIONS "http://localhost:8081/api/rest/cart" -H "Origin: http://localhost" -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: X-SALES-CHANNEL, X-CW-TOKEN, accept"
# typical response
* Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8081 (#0)
> OPTIONS /api/rest/cart HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/7.63.0
> Accept: */*
> Origin: http://localhost
> Access-Control-Request-Method: POST
> Access-Control-Request-Headers: X-SALES-CHANNEL, X-CW-TOKEN, accept
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Origin: http://localhost
< Vary: Origin
< Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS,HEAD
< Access-Control-Allow-Headers: X-SALES-CHANNEL, accept
< Access-Control-Allow-Credentials: true
< Content-Length: 0
< Date: Sun, 06 Sep 2020 10:06:31 GMT
< |
Sending the request will require appropriate headers to be sent:
Code Block | ||||
---|---|---|---|---|
| ||||
# GET request to retrieve the cart from an allowed origin
curl -v -X GET "http://localhost:8081/api/rest/cart" -H "accept: application/xml" -H "X-SALES-CHANNEL: localhost" -H "Origin: http://localhost"
# Typical positive response
* Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8081 (#0)
> GET /api/rest/cart HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/7.63.0
> accept: application/xml
> X-SALES-CHANNEL: localhost
> Origin: http://localhost
>
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Origin: http://localhost
< Vary: Origin
< Access-Control-Allow-Credentials: true
< Pragma: no-cache
< Expires: Thu, 01 Jan 1970 00:00:00 GMT
< Cache-Control: no-cache
< Cache-Control: no-store
< Set-Cookie: X-CW-TOKEN=304b592c-3963-4dcc-9bbf-c8b5973d0a3a; Version=1; Max-Age=864000; Expires=Wed, 16-Sep-2020 10:09:01 GMT; Path=/
< X-CW-TOKEN: 304b592c-3963-4dcc-9bbf-c8b5973d0a3a
< Content-Type: application/xml
< Transfer-Encoding: chunked
< Date: Sun, 06 Sep 2020 10:09:02 GMT
<
* Connection #0 to host localhost left intact
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> ... |
Code Block | ||||
---|---|---|---|---|
| ||||
# GET request to retrieve the cart from an unknown origin
curl -v -X GET "http://localhost:8081/api/rest/cart" -H "accept: application/xml" -H "X-SALES-CHANNEL: localhost" -H "Origin: http://nonallowed.com"
# Typical negative response
* Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8081 (#0)
> GET /api/rest/cart HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/7.63.0
> accept: application/xml
> X-SALES-CHANNEL: localhost
> Origin: http://nonallowed.com
>
< HTTP/1.1 403 Forbidden
< Server: Apache-Coyote/1.1
< Content-Length: 20
< Date: Sun, 06 Sep 2020 10:15:07 GMT
<
* Connection #0 to host localhost left intact
Invalid CORS request |