Tag: rest

The wcf:rest tag sends REST requests.

This JSP tag takes input and sends out REST requests, and then composes responses in a specified format. A REST tag, which is defined as a template, does not send out REST requests but persist its parameters in memory as default input. Then, it provides a mechanism that can reuse the template without identifying all parameters, only the modified ones. This approach is similar to the expressionBuilder in the wcf:getData tag REST access profile. A parameter is passed in to the REST tag to determine the server calculation and how much detailed data is being queried for the resource. It supports two format types. One format type is the same as the traditional access profile and search profile in a web service, a meaningful string that indicates only the querying details. the other format type is a detailed one, which identifies all required fields of the resource.

One REST tag might have multiple param tags. These tags are composed into the REST request to the REST server as a request parameter or request body, which include common parameters such as langId, currency, pageSize wcf:header.

One REST tag might have multiple header tags. These tags are composed into the REST request to the REST server as a request header, which includes parameters such as WCToken and WCTrustedToken.

The wcf:rest tag caches REST API calls at the request-level by using the call signature. For more information, see Caching strategies for REST services.

Tag information
Tag information
Body Content	`JSP`

Attributes

Attributes
Name	Required	Request-time	Type	Description
`var`	`false`	`true`	`java.lang.String`	This parameter identifies the variable name, which will be used to be put into persistent scope like session or request. When the tag is declared as a template, this parameter can be ignored.
`url`	`false`	`true`	`java.lang.String`	This parameter identifies the actual URL of the REST service. This parameter supports absolute or relative addresses. For relative addresses, a developer must identify the path that begins from the resource name. The system adds the host name, servlet path, and store name automatically. For relative addresses, a developer also needs to specify the HTTP schema, which defaults to `http`.
`schema`	`false`	`true`	`java.lang.String`	This parameter specifies the schema when the URL parameter is not an absolute path. The tag system gets some default value from configuration as the host name, context path and storeId. the schema parameter is specified here.
`accessProfile`	`false`	`true`	`java.lang.String`	The accessProfile is used to invoke the backend web service, which decides how much data is requested, similar to the fields parameter. The access profile is pre-configured on the REST server and cannot be changed. When this parameter is specified, the REST framework uses the transmitted one to replace the default one.
`searchProfile`	`false`	`true`	`java.lang.String`	In catalog-related REST services, searchProfile is used to invoke the backend web service, which decides how much data is requested, similar to the fields parameter. The searchProfile is pre-configured on the REST server and cannot be changed. When this parameter is specified, the REST framework uses the transmitted one to replace the default one.
`format`	`false`	`true`	`java.lang.String`	This parameter decides the output variable’s format, which can be JSON, XML, or raw. Setting the value to `json` gives an object of type JSONObject or JSONArray depending on the data returned by the REST API; `xml` gives an object in type `org.w3c.dom.Document`; and `raw` gives an object in String type. The default value for this parameter is `json`.
`cached`	`false`	`true`	`java.lang.String`	Client-side caching can be used with Storefront JSP files if the REST service that is being called is marked as `cacheable`. (Note that in the case of the Aurora Store, the client is the application server (servlet container) hosting the JSP pages that include the REST tags, and so caching will occur on the application server, and not in the browser that is consuming the output of the JSP pages.) In order to use client-side caching, set the value of `cached` to `"true"`. Responses for REST requests are based on the preceding URL and parameters are cached inside the data cache that is called `RESTTagCache`, with the `services/cache/WCRESTTagDistributedMapCache` cache JNDI name. This caching is applicable to REST services provided by both HCL Commerce and HCL Commerce search servers.
`scope`	`false`	`false`	`java.lang.String`	The scope of the REST service.
`headerStrategy`	`false`	`false`	`java.lang.String`	This parameter decides how the HTTP headers are composed in the tag. The following values are allowed: `ignore` . The tag ignores headers in parent request and respects only the headers with in tag body `inherit`. The tag respects only the header keys in tag body. You do not need to specify the values as the tag gets the values from the parent request. `mix`(default). The tag gets all header values from the parent request as a base. If you also specify a value with the same key in the tag body that is in the header, the value is also added.
`connectTimeout`	`false`	`false`	`java.math.BigInteger`	The time to wait, in milliseconds, before an HTTP connection to the target server is established. The default value is 30000.
`readTimeout`	`false`	`false`	`java.math.BigInteger`	The time to wait, in milliseconds, before a response is obtained. The default value is 30000.

elements

The wcf:rest tag contains the following elements:

wcf:header, which adds an HTTP header to a REST request.
wcf:var, which sets the variable within a REST request.

Variables

No variables are defined for the wcf:rest tag.

Example

Normal usage to get a product
<wcf:rest var="product" url="productview/byId/10001"/>

Troubleshooting

Some parameters are encoded by default into the REST call. The default parameter wcsRestTagSkipMandatorySearchEncoding in particular can cause unexpected behavior if you do not take it into account when constructed REST calls. For example, the following call fails:

    <wcf:rest var="myProductData" url="/store/{storeId}/productview/{partNumber}">
     <wcf:var name="storeId" value="12051" encode="true"/>
     <wcf:var name="partNumber" value="VESTS-FabricBackVest_SKU" encode="true"/>
    </wcf:rest>
    ${myProductData}
result:
{"responseCode":404}

This error occurs because url="/store/{storeId}/productview/{partNumber}" is encoded on the server side. This encoding is controlled by the wcsRestTagSkipMandatorySearchEncoding attribute in the page context, which changes the incoming /store/{storeId}/productview/{prtn} to /store/{storeId}/productview/%7Bprtn%7D. This results in an incorrect partNumber being returned.

You can avoid this problem by adding the attribute to the page context directly, as wcsRestTagSkipMandatorySearchEncoding=true. However, this is a mandatory search parameter. A better solution is to let JSP resolve the value. For example, the following call will succeed:

<c:set var="partNumber" value="${value for the part number}"/>
<wcf:rest var="myProductData" url="/store/{storeId}/productview/${partNumber}">
     <wcf:var name="storeId" value="12051" encode="true"/>
    </wcf:rest>