Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

For detailed documentation on interfaces provided by REST API please refer to swagger spec

Platform 

Label
Body3.7.0+
 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.

Each API request has an optional authentication token to correlate with customer virtual session. In versions up to 

Label
Body3.6.x
 it was accomplished using yc header, in 
Label
Body3.7.0+
 this header is renamed to X-CW-TOKEN.

CORS support has been introduced in 

Label
Body3.7.0+
 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.

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
Body3.7.0+

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
languagebash
titlePre-flight request check
# 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
languagebash
titleValid request
# 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
languagebash
titleInvalid request
# 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