Feature Pack 4 or later

WebSphere Commerce REST API

WebSphere Commerce REST services are JAX-RS REST services that are built on top of Apache Wink. The implementation classes contain JAX-RS annotations such as @Path, @Produces, @Consumes, @QueryParam, and @PathParam.

Query parameters

In addition to the query parameters specified in each REST service API, the following optional query parameters are available for all REST services. The REST request URL might include one or more query parameters, if needed:
responseFormat
The response format of the request. JSON and XML formats are supported by default. The responseFormat values are xml or json. The default value is json.

Feature Pack 7JSON is the only response format that is supported by the WebSphere Commerce search REST API by default. For example, in the CategoryViewHandler, ProductViewHandler, and SiteContentHandler resources denoted by (Search).

Feature Pack 8JSON and XML response formats are supported by default.

For custom formats, use lowercase letters for the response format value. For example, responseFormat=custom.

The response format of the request is determined by using the following precedence: the responseFormat query parameter in the URL, and then the HTTP Accept request header. Otherwise, json is the default response format.

langId
The language ID used during the query. If not specified, the default store language ID is used.
langId takes precedence over locale when determining which language the REST response uses, where locale is used as a fallback when langId is not specified.
locale
The locale of the request.
For example, locale=en_US for US English.
langId takes precedence over locale when determining which language the REST response uses, where locale is used as a fallback when langId is not specified.
currency
The currency that is used to display monetary values in the feed data.
For example, currency=USD for US Dollars.
Feature Pack 6 or latercatalogId
Feature Pack 6 or laterThe catalog ID used during the query. If not specified, the default store catalog ID is used.
Feature Pack 6 or laterforUser
The user name for the request.
Feature Pack 6 or laterforUserId
The user ID for the request.
Feature Pack 6 or laterworkspace.name
The name of the workspace to use.
Feature Pack 6 or laterworkspace.taskGroup
The identifier of the taskgroup within the workspace.
Feature Pack 6 or laterworkspace.task
The identifier of the task within the workspace.
Feature Pack 7 or later

WebSphere Commerce search query parameters

The following query parameters are specific to the WebSphere Commerce search REST API, such as the CategoryViewHandler, ProductViewHandler, and SiteContentHandler resources.
profileName
An optional search profile name that can be specified. It must be listed under the Search-Rest/WEB-INF/config/com.ibm.commerce.rest/wc-rest-resourceconfig.xml configuration file for the resource that is being requested.
For example, for a service with the following URI:

<GetUri uri="store/{storeId}/categoryview/byId/{categoryId}"
description="Get category by unique ID"
searchProfile="IBM_findCategoryByUniqueIds,IBM_Admin_findCategoryByIds"/>
The IBM_Admin_findCategoryByIds search profile can be specified, while IBM_findCategoryByUniqueIds is the default search profile when the profileName is not specified.
responseTemplate
The structure of response that is being used.
A value of 0 generates BOD-like responses for the responsive Aurora starter store, while a value of 1 generates REST responses.
The default value is 0.
Field name mapping definitions are used to leverage different fields in responses. The mappings are divided into the following categories:
CatalogEntryView
Maps the catalog entry section inside the Product REST responses.
CatalogGroupView
Maps the category section inside the Category REST responses.
WebContentView
Maps the web content section inside the SiteContent REST responses.
The mappings are stored in the Search_eardir/xml/config/com.ibm.commerce.catalog/wc-component.xml file.

Authentication

Some REST services require authentication. To use these REST services, you must first get authentication data by using one of the three identity services:
loginidentity
Uses a user name and password to authenticate a registered user.
guestidentity
Creates an identity for a guest user.
ltpaidentity
Uses an LTPA token to authenticate a user.
You must send a POST request to one of the REST resources, where the response contains the following data:

{
  "WCToken": "xxxxxxxxxxxxxxxxxxx",
  "WCTrustedToken": "xxxxxxxxxxxxx",
  "personalizationID": "1321550980363-1",
  "userId": "2"
}

After successfully obtaining the authentication data, you must pass the WCToken and WCTustedToken in the HTTP header for every request that requires authentication. If a request is sent over HTTP, pass the WCToken in the HTTP header. That is, do not pass the WCTrustedToken in HTTP requests, as it might be shown. However, both WCToken and WCTrustedToken must be sent if a request is sent over HTTPS.

The following snippet is an example for setting the WCToken and WCTrustedToken in the HTTP header:

HttpPost request = new HttpPost(secureUrl);

request.addHeader("Content-Type", "application/json");
request.addHeader("WCToken", wcToken);
request.addHeader("WCTrustedToken", wcTrustedToken);
Feature Pack 8

HTTP Basic Authentication

Using the HTTP basic authentication standard avoids maintaining a session. Instead, the REST API on the WebSphere Commerce server can be called, specifying the user name and password on every request.

This is done by using the Authorization header in the following way:
  1. The user name and password are combined into a string called username:password. User names and passwords that contain a colon character (:) are not supported.
  2. The resulting string literal is then encoded using the RFC2045-MIME variant of Base64, except it is not limited to 76 characters per line.
  3. The authorization method and a space is then put before the encoded string. For example, Basic .
For example, if the user agent uses Aladdin as the user name and open sesame as the password, the header is formed in the following way:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Feature Pack 7 or later

Personalization ID

The personalization ID must be explicitly passed in on every REST call, as the services might call the marketing engine, which in turn might require the personalization ID. For example, the catalog search REST API uses the marketing component to associate search terms by default.

The WCPersonalization header is used by clients that use the REST Token Authentication mechanism. For example, this ID is used by default for getMarketingSpotData, and catalog search calls. The header ensures that there is no interference with cache keys for calls that do not require it.

The personalization ID is extracted from a call in the following priority:
  1. Use a URL parameter or in the request body if explicitly used by a method.
  2. Use the WCPersonalization HTTP header, if present.
  3. Use the WC_PERSISTENT cookie if cookie consumption is allowed and the cookie exists.
  4. Extract the personalization ID from the current session, if one exists.
  5. Otherwise, the personalization ID is null.

Pagination

Data that is returned by a REST API with support for pagination can be manipulated with the following parameters:

pageSize
Maximum number of objects to return.
pageNumber
Number of the page to return, starting at 1.

Internally, this data is translated with the formula: startNumber = (pageNumber - 1) * pageSize;

If either of those numbers is zero or less (the default value if not specified), then paging isn't used.

Example, with a result that returns: ["a","b","c","d","e","f","g","h","i","j","k"]

pageSize pageNumber Result
-1 -1 ["a","b","c","d","e","f","g","h","i","j","k"]
-1 0 ["a","b","c","d","e","f","g","h","i","j","k"]
-1 1 ["a","b","c","d","e","f","g","h","i","j","k"]
0 -1 ["a","b","c","d","e","f","g","h","i","j","k"]
0 0 ["a","b","c","d","e","f","g","h","i","j","k"]
0 1 ["a","b","c","d","e","f","g","h","i","j","k"]
0 2 ["a","b","c","d","e","f","g","h","i","j","k"]
5 -1 ["a","b","c","d","e","f","g","h","i","j","k"]
5 0 ["a","b","c","d","e","f","g","h","i","j","k"]
5 1 ["a","b","c","d","e"]
5 2 ["f","g","h","i","j"]
5 3 ["k"]
5 4 []
15 -1 ["a","b","c","d","e","f","g","h","i","j","k"]
15 0 ["a","b","c","d","e","f","g","h","i","j","k"]
15 1 ["a","b","c","d","e","f","g","h","i","j","k"]
15 2 []

HTTPS versus HTTP

Some REST services must be sent securely over SSL (Secure Sockets Layer). When a REST service requires HTTPS, the request must be sent over HTTPS. The Rest.war/WEB-INF/config/com.ibm.commerce.rest/wc-rest-security.xml file defines the following REST services that require SSL, where the resource URLs defined in this file are used to match the request URL:

<sslConfig resource="store/{storeId}/cart/@self/checkout" enabled="true"/>
<sslConfig resource="store/{storeId}/cart/@self/precheckout" enabled="true"/>
<sslConfig resource="store/{storeId}/cart/@self/payment_instruction" enabled="true"/>
<sslConfig resource="store/{storeId}/cart/@self/shipping_info" enabled="true"/>
<sslConfig resource="store/{storeId}/guestidentity" enabled="true"/>
<sslConfig resource="store/{storeId}/loginidentity" enabled="true"/>
<sslConfig resource="store/{storeId}/ltpaidentity" enabled="true"/>
<sslConfig resource="store/{storeId}/order" enabled="true"/>
<sslConfig resource="store/{storeId}/person" enabled="true"/>
<sslConfig resource="store/{storeId}/wishlist" enabled="true"/>
Feature Pack 7 or laterPartial authentication is enabled by default in the wc-rest-security.xml file, indicated by the partialAuthentication flag. For example:

<security>
   <partialAuthentication resource="store/{storeId}/wishlist" method="POST" enabled="true"/>
</security>
Where each resource listed as partialAuthentication=true is allowed to consume the partial authentication stored in the WC_PERSISTENT cookie. This configuration is only used if cookie consumption is allowed on the REST API. The default value is false. When a service is called, the service URL is matched with the resource patterns, starting with the longest pattern, matching the behavior of the sslConfig nodes in the file.

HTTP method overrides

You must use a POST request and HTTP method override header, if your web server allows only the following methods:
  • GET
  • POST
And does not allow the following methods:
  • PUT
  • DELETE
For PUT methods, set the X-HTTP-Method-Override header to PUT:

X-HTTP-Method-Override: PUT
For DELETE methods, set the X-HTTP-Method-Override header to DELETE:

X-HTTP-Method-Override: DELETE
Feature Pack 7 or later

Controller command services

The following list summaries the recommendations and best practices when you are creating or customizing REST controller command services:
  • Create a resource handler for the controller commands that use the same noun by extending the AbstractClassicResourceHandler class. The recommended naming convention for the resource handler is ControllerCommandNounCmdHandler. For example, OrderItemCmdHandler.java.
  • The URL naming convention for the controller command can follow one of the following methods, depending on your requirements:
    1. Following Create, Read, Update, and Delete (CRUD) operations:
      • For Create: POST, store/{storeId}/{ControllerCommandNoun}. For example, store/11051/orderitem.
      • For Update: PUT, either store/{storeId}/{ControllerCommandNoun}. For example, store/11051/orderitem, or

        store/{storeId}/{ControllerCommandNoun}/{byCriteria}/{criteriaIdentifier}. For example, store/11051/orderitem/byOrderItemId/45002.

      • For Delete: DELETE, store/{storeId}/{ControllerCommandNoun}/{byCriteria}/criteriaIdentifier. For example, store/11051/orderitem/byOrderItemId/45002.
    2. Following generic naming conventions that are based on actions:
      • POST, store/{storeId}/{ControllerCommandNoun}/{action}.

        For example, store/11051/order/copy, store/11051/order/calculate, or store/11051/orderitem/move.

  • The command parameters (name-value pairs) can be sent as the URL path parameters, as the URL query parameters or in the request content, or both. They must be set to the request properties before the command is called.
  • The response properties (TypedProperty class) are serialized and returned after the command is run.

For more information and samples, see Best practices for mapping REST API methods to controller commands.

Feature Pack 7 or later

Data bean services

The following list summaries the recommendations and best practices when you are creating or customizing REST data bean services:
  • Create a resource handler for each data bean that uses the same noun by extending the AbstractClassicResourceHandler class. The recommended naming convention for the resource handler is DataBeanObjectDataBeanHandler. For example, CatalogDataBeanHandler, OrganizationDataBeanHandler.
  • The URL naming convention for the resource handler is store/{storeId}/{DataBeanObject}. For example, store/11051/catalog.
  • The data bean parameters (name-value pairs) are expected to be sent in the content by using a POST request.
  • The response properties (TypedProperty class) are set by the resource handler, serialized, and returned.
  • An accessProfile query parameter should be used when you are filtering the amount of return data.

For more information and samples, see Best practices for mapping REST API methods to data beans.

Feature Pack 7 or later

WebSphere Commerce search REST APIs

The REST classes that are denoted by (Search) in the title are applicable to the WebSphere Commerce search server.

They have the following benefits over the BOD-based REST services:
  • The services are served by the search server and can be separately scaled from the WebSphere Commerce server. Instead, the WebSphere Commerce server is used for processing transactional requests.
  • The WebSphere Commerce search REST API is built to extract data from Solr queries, avoiding the need for the BOD mediation layer.
Note: Attributes that are not managed by the Attribute Dictionary are not indexed or returned by default in search-based REST responses. You must either migrate your attributes to the Attribute Dictionary, or create a custom postprocessor to fetch the applicable attributes to catalog entries in the response, and then add them to the search-based REST response.
Feature Pack 7 or later

Validation between WebSphere Commerce and WebSphere Commerce search in B2C and B2B scenarios

The following validation behavior exists between WebSphere Commerce and WebSphere Commerce search in B2C and B2B scenarios:
B2C
Performing a REST service callback to WebSphere Commerce for identity revalidation is not required in the B2C scenario, as the shopper identity is not required for storefront searching and browsing scenarios. Therefore, whether the browser request comes in as a generic, guest, or authenticated shopper is irrelevant. All the users get the same public content and therefore no identity revalidation is required.
Note: The exception case is where partial authentication is not allowed on the search server. In this case, a revalidation (BCS) callback is required whenever a partially authenticated cookie or token is passed in from the header.
B2B
A contract ID is explicitly passed in from the URL in the B2B scenario. The contract revalidation is performed by using JDBC directly against the database.
Note: When entitlement check is disabled, there is no BCS callback to WebSphere Commerce and the contract that is passed in is ignored at runtime.
Feature Pack 7 or later

Interoperability

The WebSphere Commerce REST APIs can use session cookies created by the WebSphere Commerce store runtime for authentication. That is, a client can mix requests to the WebSphere Commerce REST APIs and the WebSphere Commerce store runtime within the same user session.

The REST API interoperability framework supports the following scenarios:
  • The WebSphere Commerce REST API can support web authentication cookies if AuthenticationAllowedUsingCookies is set to true in the WC\xml\config\com.ibm.commerce.foundation-fep\wc-component.xml file.
  • Partial authentication (persistent sessions) is enabled by default in the wc-rest-security.xml file for services that do not expose sensitive data. For example, for the following resources:
    
      <partialAuthentication resource="store/{storeId}/productview" method="GET" enabled="true"/>
      <partialAuthentication resource="store/{storeId}/categoryview" method="GET" enabled="true"/>
      <partialAuthentication resource="store/{storeId}/sitecontent" method="GET" enabled="true"/>
    
  • WebSphere Commerce allows simultaneous web and REST sessions for the same user.
  • Feature Pack 8The following WebSphere Commerce REST APIs can also be configured to create or update session cookies by setting the updateCookies query parameter to true:
    • POST /store/{storeId}/person
    • POST /store/{storeId}/guestidentity
    • DELETE /store/{storeId}/guestidentity/@self
    • POST /store/{storeId}/loginidentity
    • DELETE /store/{storeId}/loginidentity/@self
    • POST /store/{storeId}/ltpaidentity
    • DELETE /store/{storeId}/ltpaidentity/@self

Limitations

Consider the following limitations when you are working with the WebSphere Commerce REST API:
  • Review the available REST services to ensure the functionality that you are implementing is available. For example, promotion codes are not supported by default when you are using REST services in the CartHandler pre-checkout and checkout flows.
  • REST services are primarily designed to work with the Aurora starter store. REST services are not supported in starter stores that support the B2B direct business model, for example the Elite starter store.
  • REST API handlers rely on WebSphere Commerce search to function correctly. For example, the ProductViewHandler and CategoryViewHandler use search-based catalog navigation. You must enable WebSphere Commerce search, or customize REST services to suit your business requirements when you are working with these handlers.
  • Feature Pack 4Feature Pack 5REST services are not supported under store preview and workspaces. REST requests do not respect the preview context. That is, all requests use the base schema and not the workspace schema.

    Feature Pack 6 or laterRest services are now supported under store preview if you enable preview support for RESTful applications.

  • Feature Pack 6 or laterData compression is not supported by default, as it might result in search errors in the storefront.
  • Feature Pack 7JSON is the only response format that is supported by the WebSphere Commerce search REST API by default. For example, in the CategoryViewHandler, ProductViewHandler, and SiteContentHandler resources denoted by (Search).
  • REST services that use secure (HTTPS) requests to retrieve e-Marketing Spot data are not supported by default. To make secure requests for retrieving e-Marketing Spot data, you must first apply the interim fix for APARJR50253.

WebSphere Commerce REST API

WebSphere Commerce REST services use the following high-level Wink stack:
  • Feature Pack 4Feature Pack 7Feature Pack 5Feature Pack 61.0
  • Feature Pack 81.4.0
The following topics contain a list of resources that are provided by the WebSphere Commerce REST API. Each REST resource contains information such as URLs, descriptions, and sample input and output data.