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.
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
- Uses a client-server system.
- Stateless.
- Supports caching of resources.
- Proxy servers are supported.
- Uses logical URLs to identify resources.
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 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
- 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
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.
- Social applications
- These applications are rendered within social containers such as Facebook. Social applications can extend shopping and customer experiences.
- Kiosk/desktop applications
- These applications leverage HCL Commerce services to bridge store location shoppers with the online store and services.
REST services interaction
- Authenticates a registered user or creates a guest user.
- Invokes a Member service request.
- Returns an authenticated identity.
- Creates authentication tokens.
- Returns the WCToken and WCTrustedToken tokens.
- Generates a response in the requested format.
- Returns a response object to the client.
- Makes a service request with security tokens.
- Invokes request handlers and BCS.
- Verifies security tokens by runtime.
- Maps JAX-RS resources to HCL Commerce component services, generates, and sends service requests.
- Returns the result as a Service Data Object (SDO).
- Maps the SDO to the requested data format.
- Returns the response object to the client.
- Makes a service request with security tokens.
- Invokes request handlers and BCS.
- Verifies security tokens by runtime.
- Maps JAX-RS resources to:
- HCL Commerce controller commands to perform the command.
- HCL Commerce data beans to perform data bean activation.
- Returns the results in:
TypedProperty
by controller command.TypedProperty
by resource handler.
- Returns the response object to the client.
JSON and XML response formats are supported by default.
General query parameters
- responseFormat
- The response format of the request. JSON and XML formats are supported
by default. The responseFormat values are
xml
orjson
. The default value isjson
.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.
- locale
- The locale of the request.
- currency
- The currency that is used to display monetary values in the feed data.
- 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.
Limitations
- 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.