...
REST API can be used by mobile, tablets and desktop applications to support clients that wish to develop native applications that use the YC platform as an e-commerce engine. This is especially true in recent years with booming iPhone and Android mobile applications. However it is not limited just to mobile as there is potential for specialised call centre and business-to-business (B2B) desktop applications.
...
With rise of specialised CMS software many businesses wish to manage their Internet presence using unified approach via tools such as Adobe CMS and Alfresco (amongst many others). YC REST API allows allow to call e-commerce services from within those external CMS supplying catalog, profile and order data as well as facilitating storefront functions. Therefore corporate branding is maintained by external CMS but all data presented to client and complex e-commerce service layer is provided by YCthe platform.
Technical specification
...
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 add 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 |