| Table of Contents |
|---|
Overview
| Warning | ||||
|---|---|---|---|---|
This cookbook was written using
|
REST API is facilitated by Spring MVC where controllers are mapped to XML and JSON view resolvers. The choice of whether to use XML or JSON in request and/or response body is controlled via request headers: Content-Type for request body type and Accept for the response body type. Currently only XML and JSON modes are supported with "application/xml" and "application/json" values respectively. Request and response type in all YC REST all REST API calls are independent of each other, so it is possible to send JSON request and receive XML or JSON response and send an XML request and receive XML or JSON response - it all depends on the values in "Content-Type" and "Accept" headers sent with the request.
Customer session is maintained using token and/or cookies headers. Token is specified using yc header, whereas cookie is specified by yc cookie. Note that token is given higher priority and is examined first. Each REST API call response contains both yc header and ycboth the header and the cookie. Third party applications must provide this token and/or cookie for every subsequent call to maintain customer session.
REST API is represented by a number of controllers each of which is focused on particular functional area:
| Controller | Functional area |
|---|---|
| AuthenticationController | Login, logout and login state check |
| CartController | Viewing cart, mutating cart and wishlist and checkout (including checkout options) |
| CategoryController | Category navigation |
| ContentController | Content navigation and viewing |
| CustomerController | Viewing and updating profile, managing address book (including country options), viewing wish lists, viewing recently viewed items, viewing order history |
| NodeController | Viewing basic node information |
| ProductController | Viewing product and SKUs, viewing associations and tracking product views |
| SearchController | Product search and navigation |
We strongly advise to refer to javadoc for controllers which show request parameters and depict example responses.
...
- shop resolution by domain (as per shop instance URL mapping)
- cart resolution by token or cookie (at this point yc header and yc cookie are written to the response)
- language resolution either from cart or from request (provided that language is enabled for given shop)
...
Profile summary interface allows to view and update basic profile information and additional information for shop configured customer profile attributes.
...
Address book interface allows to view list of addresses by type (S for shipping and B for billing). Note that addresses are pre-filtered by shop allowed countries for shipping and billing addresses.
Since address objects rely upon location (country and state) this interface provides options for available countries per address type and states of particular country.
...
Note that updating wish list items of all types is done via cart controller command interface since some operations with wish list directly influence cart state. Use addToWishListCmd and removeFromWishListCmd commands to add and remove wish list items respectively. For more details on parameters to these commands refer to ShoppingCartCommand javadocs.
Recently viewed flow
Recently viewed interface support both authenticated and anonymous customers and allows to view product view history in current session. The tracking on the product views is automatic and is done every time product is viewed using GET /product/\{id\} interface.
Order history
...
Response for the search call is a single page of products results with additional information about filtered navigation, available sorting and paging options and total results count.
| Tip |
|---|
| This interface can be used for AJAX search suggest. Make sure that search request specifies includeNavigation=false in this case to avoid unnecessary processing. |
Checkout flow
Checkout flow is all about populating the shopping cart and then placing an order.
Cart mutation processes such as adding/removing/updating products, adding/removing coupons and editing order message are all facilitated by PUT /yes-api/rest/cartcommand interface. For more details on parameters to these commands refer to ShoppingCartCommandjavadocs.
When customer is ready to checkout there are four steps that they pass through.
...
Checkout step 3: choose shipping method where customer selects the shipping method they wish to use. Note that shipping method influences available payment options.
...
Step 4 finishes with PUT /order/preview call that shows all details for newly created temporary order and additional hints for payment processing. At this point third party system (e.g. mobile application) must identify whether this payment method requires transfer of control to third party payment system (e.g. redirect to PayPal web site, or some payment mobile app) or whether YC can the platform can process this payment.
If YC can the platform can process the payment it is made by POST /order/place call.
Note that payments that require payment confirmation callbacks will be processed by payment callback filters as they normally would for web site.
Resources
- REST API overview
- Live Swagger specification
...
- UI (Commerce API)
- Live Swagger UI (Mission Control API)
if "token expired" message appears, please refresh the page
| Tip |
|---|
| More in-depth articles on shop specific REST API configurations are available upon request |