Feature Pack 4 or later

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.

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

Feature Pack 7 or laterREST 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.

Feature Pack 8You 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.

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 WebSphere 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 WebSphere Commerce

RESTful applications can be developed on several platforms for WebSphere 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 WebSphere 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 WebSphere 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 WebSphere Commerce server.
Kiosk/desktop applications
These applications leverage WebSphere Commerce services to bridge store location shoppers with the online store and services.
Feature Pack 7 or later

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 WebSphere 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:
    • WebSphere Commerce controller commands to perform the command.
    • WebSphere 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.

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

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

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.

Feature Pack 8The WebSphere Commerce REST API is expanded in Feature Pack 8 to include support for additional B2C functionality in the Aurora starter store, and introduce B2B-specific functionality. In addition, the REST framework is updated to simplify the creation and consumption of REST APIs. For example, best practices when working with REST services, and configuration-based command and data bean mapping.

Feature Pack 8A live version of the WebSphere Commerce REST API is available in a web browser on your WebSphere Commerce test server using the Swagger UI. It is composed of a set of static HTML, CSS, and JavaScript that dynamically documents the available REST API on the WebSphere Commerce test server.

For more information, see Swagger UI.