URL structure for Web service feeds

Basic RESTful URL structure

http://host_name/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 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 your 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 if you want 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 com.ibm.commerce.context.audit.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 feeds) A random number that uniquely identifies a wish list. This access key is required in URLs for wish lists 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.

In the URL path, parameter names, and parameter values, use URL encoding to encode all special characters. For example, encode an ampersand character (&) as %26, spaces as %20, and the percent sign (%) as %25. For example, for an identifier of Black&White, include this in the URL as Black%26White. For more information on URL encoding, look up the URL specification (RFC 1738).