WebSphere Commerce REST API

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.

JSON 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).

JSON 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.

catalogId

The catalog ID used during the query. If not specified, the default store catalog ID is used.

forUser

The user name for the request.

forUserId

The user ID for the request.

workspace.name

The name of the workspace to use.

workspace.taskGroup

The identifier of the taskgroup within the workspace.

workspace.task

The identifier of the task within the workspace.

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.

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"
}

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);

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==

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.

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"/>

Partial 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.

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

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.

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.

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.

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.

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.
• The 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

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.
• REST 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.

  Rest services are now supported under store preview if you enable preview support for RESTful applications.

• Data compression is not supported by default, as it might result in search errors in the storefront.
• JSON 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 services use the following high-level Wink stack:

• 1.0
• 1.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.

• WebSphere Commerce REST API
• WebSphere Commerce REST API
• WebSphere Commerce REST API