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.
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.
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 WebSphere 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 WebSphere 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 WebSphere 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 WebSphere 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 WebSphere 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:
- WebSphere Commerce controller commands to perform the command.
- WebSphere 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.
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 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 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.
- 1.0
- 1.4.0
The 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.
For more information, see Swagger UI.