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 required to return results (state transfer), eliminating the need for cookies when we 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.

We 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:

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 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. We 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 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. We can add our 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:

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.

REST services interaction

The following diagram shows the REST services interaction flow:

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.

   JSON and XML response formats are supported by default.

Limitations

Consider the following limitations when we are working with the WebSphere Commerce REST API:

• Review the available REST services to ensure the functionality that we are implementing is available. For example, promotion codes are not supported by default when we 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 WebSphere Commerce search to function correctly, as the search services use search-based catalog navigation. We must enable WebSphere Commerce search, or customize REST services to suit your business requirements when we 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.

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.

• Creating and customizing REST services
  We can create and customize our own REST services with WebSphere Commerce Developer.

• Working with REST services
  We can work with existing REST services to meet your business needs.

• REST authentication
  Consider the WebSphere Commerce authentication issues and features such as user sessions with REST services.

• REST security
  Consider the WebSphere Commerce security issues and features such as authorization, and access control policies for REST services.

• REST local binding
  Local binding improves the performance of the REST framework by providing an optimized REST flow.

• REST performance
  We can optimize REST services for performance. For example, with client and server-side caching.

• REST configuration properties in the component configuration file (wc-component.xml)
  The component configuration file (wc-component.xml) contains properties to configure various REST features.

Related concepts
Location-based services
WebSphere Commerce Storefront REST API