Representational State Transfer (REST) services

Representational State Transfer (REST) is a lightweight framework for designing applications that use HTTP to make calls. REST uses HTTP to perform the Create, Read, Update, and Delete (CRUD) operations between client and server. Applications interact with the services by using HTTP, POST, PUT, GET, and DELETE operations.

HCL Commerce uses Representational State Transfer (REST) services to provide a framework that can be used to develop RESTful applications on several platforms. These platforms can include web, mobile, kiosks, and social applications.

Comparatively, REST can perform the same functions as the Simple Object Access Protocol (SOAP) and Web Services Description Language (WSDL).

REST is platform and language independent, and because it is built on HTTP, is compatible in environments behind firewalls. REST can use secure connections over HTTPS to take advantage of HTTPS security features such as encryption or username and password tokens.

REST calls include all the information that is required to return results (state transfer), eliminating the need for cookies when you are using REST services in the storefront.

REST services help facilitate the invocation of classic controller commands and the activation of data beans. They aim to provide a framework that is easy to learn and customize. The framework lets you create custom REST resource handlers that invoke controller commands to perform add, update and delete operations, or activate data beans to retrieve data.
Important: It is not recommended to use the REST classic programming framework to invoke controller commands that change session information. For example, the user ID. Sample controller commands that alter session information are the LogonCmd and LogoffCmd commands.

You can create REST services using the configuration-based controller command and data bean mapping framework. It helps create REST services and automates mappings using the restClassicSampleGen utility, and allows the activation of data beans or the running of controller commands using REST services.

Available REST API

REST services characteristics

The following list summarizes the key characteristics of the REST architecture:
  • Uses a client-server system.
  • Stateless.
  • Supports caching of resources.
  • Proxy servers are supported.
  • Uses logical URLs to identify resources.

REST services abstraction

The following diagram illustrates the various components of the REST services abstraction:
REST services abstraction diagram
Where:
  • The built-in Context Providers search for certain elements in the request such as store ID, language ID, or user identity. The Context Providers use these elements to build the appropriate context that is used to retrieve or update the Business Object Document (BOD) in HCL Commerce. The primary context providers are:
    • Business context provider
    • Security context provider
    These context providers are invoked for every request and provide context as appropriate to the resource handlers.
  • The Resource Handlers represent the entry points for resource requests and are annotated with the Path, context and any other information that they might require to handle a request. The resource handlers are responsible for coordinating the BOD request and response and converting the request and response to and from a form that is consumable by the client by using standard HTTP protocol elements. They are also responsible for composite resource representations where more than one BOD or source are integrated. In addition, the resource handlers are also responsible for ensuring that related resources are correctly identified and specified in the representation.

    Each resource handler implements com.ibm.commerce.foundation.rest.resourcehandler.IResourceHandler interface. You can customize a resource handler by overriding its methods.

  • The Helpers aid the resource handlers to bridge the BOD layer and enables reusable common code across handlers. There are also helpers for store configuration, building URI, and for enforcing transport security requirements that are specified for resource handlers.
  • Data Mappers are configuration files that are used to transform resource representations to and from BOD attributes. This enables you to declaratively customize the representation.
  • The default Entity Providers enable standard encoding of responses as JSON or XML format that is based on data mappers. You can add your own custom providers for other media types to suit your business needs.
  • Resource Templates are a mechanism to enable you to render custom representations such as XHTML using a JSP file.

REST services in HCL Commerce

RESTful applications can be developed on several platforms for HCL Commerce. The following diagram illustrates the various REST client platforms and servers:
REST client platforms and servers
Where:
Mobile Applications
REST services enable the development of mobile applications that leverage device platform-specific native user interfaces, or an embedded web browser for the user experience and REST services for data and updates.
Web Applications
Web applications can include traditional storefronts, or specific Web functionality that provide HCL Commerce functionality through REST services. The amount of web client and server interactions can vary with the REST services that characterize such applications.
On-premise Web applications denote that the application (or part of the application) runs on the HCL Commerce server.
Social applications
These applications are rendered within social containers such as Facebook. Social applications can extend shopping and customer experiences.
On-premise social applications denote that the application (or part of the application) runs on the HCL Commerce server.
Kiosk/desktop applications
These applications leverage HCL Commerce services to bridge store location shoppers with the online store and services.

REST services interaction

The following diagram shows the REST services interaction flow:
REST services interaction flow diagram
Where:
Authentication Services:
  1. Authenticates a registered user or creates a guest user.
  2. Invokes a Member service request.
  3. Returns an authenticated identity.
  4. Creates authentication tokens.
  5. Returns the WCToken and WCTrustedToken tokens.
  6. Generates a response in the requested format.
  7. Returns a response object to the client.
Business Services:
  1. Makes a service request with security tokens.
  2. Invokes request handlers and BCS.
  3. Verifies security tokens by runtime.
  4. Maps JAX-RS resources to HCL Commerce component services, generates, and sends service requests.
  5. Returns the result as a Service Data Object (SDO).
  6. Maps the SDO to the requested data format.
  7. Returns the response object to the client.
Command and Data Bean Services:
  1. Makes a service request with security tokens.
  2. Invokes request handlers and BCS.
  3. Verifies security tokens by runtime.
  4. Maps JAX-RS resources to:
    • HCL Commerce controller commands to perform the command.
    • HCL Commerce data beans to perform data bean activation.
  5. Returns the results in:
    • TypedProperty by controller command.
    • TypedProperty by resource handler.
  6. Returns the response object to the client.

    JSON and XML response formats are supported by default.

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

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.
See the description of the forUserId parameter.
forUserId
The user ID for the request.
Both the forUser and forUserId REST parameters allow you to specify that the command be executed for the specified user, even though the user that is currently logged in may be different. This is particularly useful when a customer service representative needs to assist a customer. For example, the customer service representative can update a customer's address on behalf of that customer, by specifying the customer's user name or user ID by using the REST parameters. This change in user information is only valid for the duration of the URL request for which it was specified. The forUser parameter is the value of the logon ID of the user. The forUserId parameter is the value of the user ID of the user.
Note:
  • To use the forUserId REST parameter, you must first make a separate GET /person/@self?forUserId=userId call, in order for the activity to be set up correctly.
  • If LDAP is configured as the user repository to be used with HCL Commerce, the full DN must be used as the value for this forUser parameter.
  • The user represented by forUser or forUserId must be a non-administrator. The user must also be manageable by the administrator that is executing the command. Furthermore, the administrator must play the appropriate role in the current store's organization, or any of its ancestor organizations. The access control policy that specifies which administrators and commands can use the forUser and forUserId parameters is: BecomeUserCustomerServiceGroupExecutesBecomeUserCmdsResourceGroup. By default, the administrative user must have one of the following roles to perform the forUser or forUserId operation:
    • Customer Service Representative
    • Customer Service Supervisor
    • Seller
    • Sales Manager
    • Operations Manager
    • Site administrator
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.

Limitations

Consider the following limitations when you are working with the HCL 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 for the cart pre-checkout and checkout flows.
  • REST services are primarily designed to work with the Aurora starter store.
  • REST API handlers rely on HCL Commerce search to function correctly, as the search services use search-based catalog navigation. You must enable HCL Commerce search, or customize REST services to suit your business requirements when you are working with these handlers.
  • Data compression is not supported by default, as it might result in search errors in the storefront.
  • REST APIs that are mapped to BOD services cannot handle certain special characters due to how the XPath is parsed. When special characters are encountered, a 500 Internal Server Error code is returned, as the BOD framework does not handle the exception to return a different response error code. To avoid this issue, do not use special characters such as <, >, &, ', or " in REST APIs that are mapped to BOD services.

HCL Commerce REST API

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