Add or modifying REST templates

For Spring action controller customizations to communicate with the Transaction Server and Search server, their additions and customizations must be converted into structured REST messages. The REST template maps each action controller method to the appropriate REST call over HTTP. Therefore, any modifications to default actions, or any additional action controllers or action controller methods must have corresponding REST template mappings.

The default REST templates are located in the following file: crs-web/WebContent/WEB-INF/xml/config/componentDir/rest-template-config.xml


Procedure

  1. Extend the REST template configuration file for the component we are modifying or creating into the stores web archive (crs-web.war).

    To extend this template, Copy it directly into crs-web.war/WEB-INF/xml/config/componentDir/rest-template-config-ext.xml . If it is a new component, ensure that you add it under a new component directory (componentDir).

    The location and contents of this file are as follows: REST templates define request formats for the REST services that are executed by Spring controllers on the Store server. Each action controller calls REST services as defined in REST templates for executing business logic. REST services that are defined in REST templates are grouped by resource definitions, and each resource definition is subdivided into method definitions:

    • A resource is characterized by a path which is a URI prefix that is common to a group of REST services.

    • Each method definition is characterized by the remaining path after the resource path in the full URI of a REST service.

    Each resource or method has a name. A resource name and a method name can uniquely identify a REST service. For each method definition, a template is defined for composing a REST request from the parameters of a web request. For each Spring action controller, the resource name and method name of the REST service to be executed by this controller is defined by a property of the definition of this controller in the Spring configuration XML file.

    • crs-web.war/WEB-INF/xml/config/componentDir/rest-template-config.xml

      These files contain the REST template configuration for each component.

      The contents of these files appear as such: 

        <resource path="{serverHost}/{contextPath}/store/{storeId}/loginidentity" name="loginIdentityHandler">
<serverParam name="serverHost">$WCParam.serverHost</serverParam>
<serverParam name="storeId">$WCParam.storeId</serverParam>
…
<method name="logonAndChangePassword" httpMethod="POST" path="">
<template>
<![CDATA[{"logonId" :
      "$logonId","logonPassword" :
      "$logonPasswordOld","logonPasswordNew" :
      "$logonPassword","logonPasswordVerify"
      : "$logonPasswordVerify"}]]>
</template>
</method>
…
</resource>

      Where:

        resource
        The REST resource.

          path
          The REST resource URL. The variable in this URL is dynamically changed. Therefore, it must be enclosed within the curly brackets ('{}'), and its value is defined by the following serverParam entries.

          name
          The defined resource name of the service.

        serverParam
        This element is a subelement within the resource tag.

        The variables used in the resource path. The serverHost, contextPath and storeId variables are automatically resolved to be the values for the backend WebSphere Commerce server based on the current request scheme and preview mode. Other parameters are obtained from the current request parameters.

        method
        This element is a subelement within the resource tag.

        The method definition.

          name
          The defined method name. Together with the resource name it becomes the parameter property that is defined in the action controller definition. For example, for this service example, the parameter is loginIdentityHandler.logonAndChangePassword.

          httpMethod
          The HTTP method for this REST request.

          path
          The method part of the REST resource in the URL. For example, the method path for the service /store/{storeId}/person/@self is @self. If this parameter is left empty, then the resource path URL used is the full URL.

          template
          The input values required by the REST request in JSON format. For POST, PUT, and DELETE services, the body JSON is in this template format. For GET services, the variables in the template are appended in the URL as request parameters. The variable values are found from request properties using the values in the templates without the dollar sign as the request property name. If a variable value does not have the dollar sign, the variable value in the template is the value composed to the REST request.

    Note: You do not need to configure the REST response format for the REST template. The response format is configured by the Transaction server.

  2. Modify the REST template based on the REST resource or method created, extended, or modify.

  3. Save the file.

  4. Restart the Store server.


Results

The REST messages that are passed between the Store server and the Transaction Server and Search server now conform to the new template that was configured.


Related reference
Store configuration files