Develop > Presentation layer > Work with Web service feeds


URL structure for Web service feeds

URLs that retrieve feeds from WebSphere Commerce Web services must follow a specific structure. Remote widgets for e-Marketing Spots, wish lists, and gift registries retrieve feeds using these URLs. If you are creating a custom feed from a Web service, use this URL structure in the customization. The URL structure adheres to the principles of REST (Representational State Transfer).

To display a specific e-Marketing Spot, wish list, or gift registry feed in a remote widget or a feed reader, you can form the URL for the feed using the URL structure defined in this topic. The URL structure contains parameter variables that you can replace with data specific to the feed to retrieve. If you form the URL correctly, you can view the feed by pasting the URL into a browser or feed reader that supports Atom feeds. Specific feed URL examples for e-Marketing Spots, wish lists, and gift registries are provided later in this topic.


Basic RESTful URL structure

To return a feed containing a specific instance of a noun defined by an identifier, the RESTful URL structure must use this syntax: 

http://host/wcs/resources/stores/storeId/plural_noun_name/identifier

The URL parameter variables are:

storeId

The store entity ID as defined in the STORE_ID column of the STORE table.

plural_noun_name

The pluralized name of the noun to get from the Web service for the Atom feed:

  • For e-Marketing Spot feeds, the plural_noun_name is MarketingSpotData.

  • For wish list or gift registry feeds, the plural_noun_name is GiftLists.

For custom feeds: Use the plural form of the noun. For example, if the noun is PhysicalStore or Catalog, then add an s to the noun name so it becomes PhysicalStores or Catalogs. The WebSphere Commerce convention is to use the plural form of a noun in a RESTful URL.

To view nouns available for WebSphere Commerce components, see WebSphere Commerce Web services.

identifier

The identifier for the noun data to get. The RESTful framework finds nouns by their internal or external ID.

For custom feeds: If possible, use the internal or numeric identifier for the noun so that you do not need to worry about case sensitivity. For example, if you wanted to create an Atom feed from the Catalog service for the New Products sales catalog, you would specify the unique ID of the New Products sales catalog defined for the Catalog noun. If you are creating an Atom feed from the own custom WebSphere Commerce Web service, that Web service must have an action expression that gets a noun by an internal or external ID. Exclude this parameter only to get all instances of the noun for the store.

The URL can also include the following optional query parameters to override default parameters, if required:

responseFormat

The response format of the request.

To return an Atom feed from the service, use responseFormat=atom. Other responseFormat values are xml or json.

For custom feeds: Use lower-case letters for the response format value, as shown. The response format of the request is determined using the following precedence: the responseFormat query parameter in the URL, and then the HTTP Accept request header. Otherwise, XML is the default response format.

locale

The locale of the request, for example, locale=en_US.

The locale of the request is determined using the following precedence: the locale query parameter in the URL, then the HTTP Accept-Language request header, then the application server default locale.

accessProfile

The name of the storefront access profile to use in the WebSphere Commerce Web service request. The access profile defines the data to include in the response. Access profiles are defined for each noun. Typically, storefront access profiles start with IBM_Store instead of IBM_Admin.

The access profile of the request is determined using the following precedence: the accessProfile query parameter in the URL, and then the default access profile coded in the JAX-RS resource Java class. Typically, you would not need to override the default access profile in the JAX-RS resource by including it as a query parameter in the URL.

langId

The WebSphere Commerce language, for example, langId=-1 for English.

currency

The currency used to display monetary values in the feed data, for example, currency=USD.

contentPersonalizationId

(Supported only for e-Marketing Spot feeds) A personalization ID is used by the WebSphere Commerce marketing services to identify a user to present them with personalized content. E-Marketing Spot feed URLs use the contentPersonalizationId, which is the personalization ID of the user that the feed content is personalized for, rather than the user currently viewing the remote widget or feed reader.

Here is an example: If user A shares the widget from the store page to a social network, then the contentPersonalizationId used in the URL for that widget is set to the personalization ID of user A. If user B then views the remote widget that user A embedded on the social network, the URL for the widget will still use the personalization ID of user A.

WebSphere Commerce includes the contentPersonalizationId parameter in an e-Marketing Spot feed URL when the personalization ID is available in the context, for example, when a customer shares a remote widget or subscribes to a feed from the storefront. The RemoteWidgetButton.jspf file sets this parameter in the URL. The personalization ID is obtained from the AuditContext.

numberProductsToDisplay

(Supported only for e-Marketing Spot feeds) The maximum number of catalog entries (products) to display in the remote widget or feed reader.

numberCategoriesToDisplay

(Supported only for e-Marketing Spot feeds) The maximum number of categories to display in the remote widget or feed reader.

numberContentToDisplay

(Supported only for e-Marketing Spot feeds) The maximum number of marketing content to display in the remote widget or feed reader.

guestAccessKey

(Required only for wish list and gift registry feeds) A random number that uniquely identifies a wish list or a gift registry. This access key is required in URLs for wish lists and gift registries so customers other than the list owner can view the list in a remote widget. This value is stored in the GRGFTREG table in the GUESTACCESSKEY column.


Examples of URLs that retrieve e-Marketing Spot, wish list, and gift registry feeds

The RESTful framework supports feeds from the following Web services (no customization required):

Based on the URL syntax, the following are examples of each URL using some of the mandatory and optional parameters:

Example URL for an e-Marketing Spot feed

This URL returns an Atom feed containing data from the MarketingSpotData noun for the HomePageFeaturedProducts e-Marketing Spot: 

http://mysite.example.com/wcs/resources/stores/10000001/MarketingSpotData/HomePageDealOfTheWeek
?responseFormat=atom&langId=-1&currency=USD&contentPersonalizationId=1271095292430-1

Example URL for a wish list feed

This URL returns an Atom feed containing data from the GiftList noun for a customer's wish list with the external ID 12345: 

http://mysite.example.com/wcs/resources/stores/10101/GiftLists/12345
?responseFormat=atom&guestAccessKey=-65e4895b:12726956ada:-7fad

Example URL for a gift registry feed

This URL returns an Atom feed containing the data from the GiftList noun for a customer's gift registry with the external ID 23456: 

http://mysite.example.com/wcs/resources/stores/10101/GiftLists/23456
?responseFormat=atom&guestAccessKey=-78d3567b:12726956ada:-6fbc

Notice that the URL structure for a wish list feed and a gift registry feed is the same; both feeds are from the GiftList noun.


Examples of URLs supported with customization

By customizing the RESTful framework, you can retrieve feeds from Web services other than Get MarketingSpotData and Get GiftList. When defining these URLs for the customization scenario, you use the same basic RESTful URL structure described previously. The following URLs are examples only; WebSphere Commerce does not provide a RESTful Web service for the Catalog noun or the PhysicalStore noun.

Example custom URL for a feed for a specific store catalog

This URL returns an Atom feed containing data from the Catalog noun for a specific catalog that has an internal ID of 99999: 

http://mysite.example.com/wcs/resources/stores/10101/Catalogs/99999?responseFormat=atom

Example custom URL for a feed for a list of physical stores

This URL returns an Atom feed containing a list physical stores associated to the online store 10101. In this example, all instances of the PhysicalStore noun are returned because the URL does not contain an identifier for a specific physical store: 

http://mysite.example.com/wcs/resources/stores/10101/PhysicalStores?responseFormat=atom


Related concepts

Remote widgets


Related tasks

Work with Web service feeds

Pass custom parameters to an e-Marketing Spot Atom feed

Create a custom feed from a Web service


+

Search Tips   |   Advanced Search