Tag: rest

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 using the call signature. See Caching strategies for REST services.

Tag information
Body Content JSP

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 called RESTTagCache, with the services/cache/WCRESTTagDistributedMapCache cache JNDI name. This caching is applicable to REST services provided by both WebSphere Commerce and WebSphere 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 (default). 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. 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. Default 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. We 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>
Related concepts
Representational State Transfer (REST) services

Related reference
WebSphere Commerce foundation tag library

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 called RESTTagCache, with the services/cache/WCRESTTagDistributedMapCache cache JNDI name. This caching is applicable to REST services provided by both WebSphere Commerce and WebSphere 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 (default). 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. 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. Default is 30000.
readTimeout	false	false	java.math.BigInteger	The time to wait, in milliseconds, before a response is obtained. The default value is 30000.