Overview of the RESTful Web service framework for feeds

Web services that this framework supports

If you want to retrieve a feed from any other WebSphere Commerce Web service, or from a custom Web service you have created, you must customize the framework.

RESTful Web service framework

The framework uses the REST (Representational State Transfer) architectural style. This style ensures consistency in URL formats and provides a way of getting data from a service that conforms to a set of principles. Information on the server side is considered a resource, which developers can access using Web URIs (Uniform Resource Identifiers) and HTTP. REST requires a stateless client-server architecture. You can learn more about the REST architectural style on the Internet.

The following diagram illustrates the WebSphere Commerce RESTful framework. The diagram shows the flow of events, starting from when a client initiates a request to get data from a Web service. An example is a feed reader requesting a feed from the Get MarketingSpotData service for an e-Marketing Spot that displays the Deals of the Week.

= the parts of the framework you must customize to retrieve a feed from Web services other than Get MarketingSpotData or Get GiftList.

The steps in the diagram are explained here:

1. The client initiates a RESTful HTTP GET request.

   Example: To retrieve an Atom feed for an e-Marketing Spot named HomePageFeaturedProducts in a feed reader, the URL for the GET request might look like this:

   http://host_name/wcs/resources/stores/10101/MarketingSpotData/HomePageFeaturedProducts?responseFormat=atom

   Customization point: To create a custom feed from a Web service, you must define the RESTful HTTP GET request (the URL) for your custom feed using a defined RESTful syntax.

2. The JAX-RS runtime matches the URL of the request to the appropriate JAX-RS resource. The JAX-RS resource is a Java class that converts RESTful HTTP GET requests into WebSphere Commerce service requests and returns data in either XML, JSON, or Atom format.

   Example: The JAX-RS runtime matches the URL http://host_name/wcs/resources/stores/10101/MarketingSpotData/HomePageFeaturedProducts?responseFormat=atom to the MarketingSpotData JAX-RS resource.

   Customization point: To create a custom feed from a Web service, you must create the JAX-RS resource Java class by providing input to a Java Emitter Template (JET) pattern that generates the code for the class.

3. Using the client libraries, the JAX-RS resource performs an OAGIS service request to WebSphere Commerce.

   Example: The MarketingSpotData resource constructs a GetMarketingSpotData business object document (BOD) and sends it to the WebSphere Commerce server.

4. The WebSphere Commerce Web service returns the service request results as a service data object (SDO).
5. The JAX-RS resource determines the appropriate response format based on the request. Typically, the URL specifies Atom format with the parameter responseFormat=atom. The JAX-RS runtime then matches the WebSphere Commerce service request result to the JAX-RS provider that transforms the SDO to Atom format.

   WebSphere Commerce also includes JAX-RS providers to transform SDOs to JSON and XML format.

6. The JAX-RS provider calls the appropriate feed formatting JSP files for the noun to select and format the data from the SDO.

   Customization point: To create a custom feed from a Web service, you must create the feed formatting JSP files based on the Atom Syndication Format specification, and then update a Struts configuration file to point to your custom JSP files. To change the content or configuration of an existing feed for e-Marketing Spots and wish lists, you can edit their associated feed formatting JSPs.

7. The JAX-RS provider transforms the SDO into an Atom feed, and then returns the feed to the client for display to a customer.

Concepts related to this customization

JAX-RS

A Java API for creating RESTful Web services. WebSphere Commerce provides this API.

JAX-RS resource

A Java class that converts RESTful HTTP GET requests into WebSphere Commerce service requests and returns data in either XML, JSON, or Atom format. The JAX-RS resource uses the @Path annotation to indicate which URLs the class handles.

Example: A class annotated with @Path("stores/{storeId}/MarketingSpotData") handles all URL requests matching .../stores/storeId/MarketingSpotData/...

JAX-RS provider

A Java class that transforms data from one format to another, for example, transforming SDO format to Atom format. WebSphere Commerce provides three classes that transform SDOs to Atom format, JSON format, and XML format.

Atom Syndication Format

An XML language used for providing Web feeds. The Atom Syndication Format follows standards that are different from the alternative Web feed format, RSS (Really Simple Syndication). The specification for the Atom Syndication Format is available on the Internet for your reference when developing or editing feed formatting JSP files.

Noun or resource

A noun is the logical model definition for Web services that are fronted by an XML schema. WebSphere Commerce uses its own simplified nouns, defined types, and primitive XML schema types. In a RESTful framework, noun and resource mean the same thing.

Feed formatting JSP file

A file or set of files used to format the Atom feed for an SDO, including the feed title, the feed content, and the number of entries to return in the feed. The feed formatting JSP must produce a valid output according to the Atom Syndication Format 1.0 specification.

Caching

Limitations of the RESTful Web service framework for feeds

1. The framework supports only HTTP GET methods. POST, PUT, and DELETE methods are not supported.
2. The framework can retrieve only data that a customer can view on the storefront without logging in. REST requests do not have identity or session support. For example, you cannot retrieve shopping cart data for an Atom feed because a customer must log in to see this information.