Create and customizing REST services with the BOD mapping framework

Create and customizing REST services with the BOD mapping framework

WebSphere Commerce provides a Java Emitter Template (JET) called the JET RESTful Resource pattern as part of the BOD mapping framework. The JET RESTful Resource pattern generates a JAX-RS annotated Java class that provides REST service for a specific resource. To generate these files, we must create a pattern input file that contains specifications required to implement the REST service by using a BOD noun.

Prerequisites for using the JET RESTful Resource pattern

The JET RESTful Resource pattern works on the Eclipse Modeling Framework (EMF) and uses the Java Emitter Templates (JET) to generate the source code. Ensure that EMF with JET is installed in your development environment before you begin.
Ensure that you install the JET package within the WebSphere Commerce Developer environment. See Installing the Java Emitter Template (JET) package. Ensure that the following plug-in IDs are installed:

org.eclipse.emf.codegen
com.ibm.commerce.toolkit.internal.pattern.rest

Format of the pattern input file

Pattern input files provide the required information to the JET RESTful Resource pattern in the following format:
<rest 
   componentName="component_name" 
   packageNamePrefix="package_name_prefix">
  <noun 
        name="noun_name" 
        pluralNounName="plural_noun_name" 
        resourceName="resource_name"
      actionExpression="action_expression" 
        actionExpressionSuffix="action_expression_suffix" 
        defaultAccessProfile="default_access_profile" 
        defaultExpression="default_get_xpath_expression">
       <findBy 
         expression="get_xpath_expression" 
         name="findby_name"
         accessProfile="get_access_profile"/>
       <delete 
         key="key_to_delete" 
         method="delete_method"/>
       <create 
         for="create_for" 
         method="create_method"/>
   <update 
         for="update_for" 
         method="update_method"/>
  </noun>
</rest>
Note: The resourceName does not have to match the noun name in a pattern input XML file. Ensure that the resourceName you specify does not match any of the default REST resources.
The following table describes the variables in the pattern input XML file:
Input file variable Required Description
component_name Yes The name of the component containing the Web service from which we want to create a REST service. If we are using an existing WebSphere Commerce service, obtain the component name by viewing the list in this topic:
WebSphere Commerce Web services
Examples of component names are:

Catalog
Marketing
Order

If we are creating a REST service from a custom WebSphere Commerce Web service, use the name of the component containing the custom Web service.
package_name_prefix Yes The prefix of the package containing the Java class output by this pattern.

For a REST service from a WebSphere Commerce noun, use com.ibm.commerce
For a REST service from a custom noun, use com.your_company_name.commerce, for example, com.mycompany.commerce

noun_name Yes The name of the noun to use to implement the REST service. To view nouns available for WebSphere Commerce components, see WebSphere Commerce Web services.
plural_noun_name Yes The plural form of the noun to use to implement the REST service. The convention is to specify the same singular value in a RESTful URL. For example, if a noun is Person, both noun_name and plural_noun_name should be set to be Person.
resource_name No The name of the REST resource we want to specify for a REST service.
action_expression No The action expression for the noun or its sub noun. For example: AddressBook/Contact.
action_expression_suffix No The action expression suffix for the noun or its sub noun. For example: [1].
default_access_profile Yes The name of the default storefront access profile to use for the WebSphere Commerce service request. The access profile defines the data to include in the response. Access profiles are defined for each noun in WebSphere Commerce Web services. Typically, storefront access profiles start with IBM_Store instead of IBM_Admin.
default_get_xpath_expression
No
The XPath expression for the GET service that gets all instances of a noun, rather than returning a specific instance of the noun by its identifier. Include this parameter in your pattern input file only if you need the JAX-RS resource to get all instances of a noun. For example, the Catalog noun has a GET XPath expression that gets all the sales catalogs for the store. In this case, the attribute in the pattern input file is:
defaultExpression="/Catalog[@primary='false']"
If your RESTful URL does not include an identifier, the JAX-RS resource uses the default_get_xpath_expression.
get_xpath_expression Yes 1 The XPath expression for the GET service that gets a noun using the internal or external identifier you specified in the URL in the previous procedure.
Example of an XPath expression that uses an internal identifier–Get Catalog service:
/Catalog[CatalogIdentifier[(UniqueID=)]]
This XPath expression gets a catalog by its unique ID and returns the catalog that matches the ID.
Important: When we are including the XPath expression in the pattern input file, specify the following characters for the numeric UniqueID value, regardless of what is in the documented XPath expression:
{0}
The previous example XPath expression must look like the following string in the pattern input file:
/Catalog[CatalogIdentifier[(UniqueID={0})]]
Note: WebSphere Commerce does not provide a RESTful Web service for the Catalog noun, but you could create one using the procedures in this section.
Example of an XPath expression that uses an external identifier–Get MarketingSpotData service:
/MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=)]]]
This XPath expression gets e-Marketing Spot data by its external identifier (in this case, its name) and returns the data for display to a customer.
Important: When we are including the XPath expression in the pattern input file, if the identifier value is a string, specify the following characters for the string value, regardless of what is in the documented XPath expression:
\"{0}\"
The previous example XPath expression must look like the following string in the pattern input file:
/MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=\"{0}\")]]]
findby_name Yes 1 The suffix of the method name called when the URL contains an identifier. The pattern creates a method by using this suffix for the name. In the generated Java class, the full method name is findByfindby_name. The findby_name should match the identifier specified for the XPath expression for the Get service. For example, for the Get Catalog XPath expression in the previous row, an appropriate findby_name is Id.
get_access_profile Yes 1 The name of the access profile to use for the WebSphere Commerce service get request. The access profile defines the data to include in the response.
key_to_delete Yes 1 The unique key or identifier to delete a resource in a WebSphere Commerce service.
delete_method Yes 1 The delete method of a WebSphere Commerce service client façade class, which takes Map as parameter. For example: MemberFacadeClient.deleteAddressForPerson(java.util.Map).
create_for Yes 1 The resource to be created by using a WebSphere Commerce service.
create_method Yes 1 The create method of a WebSphere Commerce service client façade class, which takes Map as parameter. For example: MemberFacadeClient.addAddressForPerson(java.util.Map).
update_for Yes 1 The resource to be updated by using a WebSphere Commerce service.
update_method Yes 1 The update method of a WebSphere Commerce service client façade class, which takes Map as parameter. For example: MemberFacadeClient.updateAddressForPerson(java.util.Map).
Note: 1 These variables are required if the respective actions (findBy, create, update, and delete) are defined. At least one action definition is required for the noun. Multiple nouns and actions are supported in the input XML pattern file. The input XML pattern file must contain unique values for noun name, key, for, and method names.

Sample pattern input file

This example input file generates the Java classes and properties files required to work with the Member service to create, update, retrieve, and delete the available resources:
<rest 
   componentName="Member" 
   internal="false" 
   packageNamePrefix="com.ibm.commerce">
  <noun 
       name="Person" 
       pluralNounName="Person" 
       resourceName="Person"
     actionExpression="AddressBook/Contact" 
       actionExpressionSuffix="" 
       defaultAccessProfile="IBM_Store_Details" 
       defaultExpression="{self=true}/Person">
    <findBy 
      expression="/Person[PersonIdentifier[(UniqueID={0})]]" 
      name="UniqueID" 
      accessProfile="IBM_Store_Details"/>
    <findBy 
      expression="/Person[Credential[LogonID={0}]] " 
      name="LogonID" 
      accessProfile="IBM_Store_Details"/>
    <delete 
      key="ContextAttribute" 
      method="deleteContextAttributeForPerson"/>
    <create 
      for="Person" 
      method="registerPerson"/>
    <update 
      for="Person" 
      method="updatePerson"/>
  </noun>
</rest>
Generating the source code
Perform the following steps to generate the source code for REST services:

Create an XML file under the customization project/location (WebSphereCommerceServerExtensionsLogic) directory and copy sample input file into it. Make your required changes to the file according to the input specifications table from the Format of the pattern input file section.
Save our changes to the file. Then, right click the file and select Run As > Run Configuration.
Select Jet Transformation, then right click and select New. Anew configuration is created.
The generated XML file appears in the Transformation Input section. Select the transformation ID as com.ibm.commerce.toolkit.internal.pattern.rest:

Select Apply > Run to start the transformation.
After successfully running the transformation, the output files are generated under the WebSphereCommerceServerExtensionsLogicproject.
Check for any compilation errors in Java classes, which might occur because of any missing JAR files in the classpath, and rectify them.

Location of the pattern output file
The pattern generates files in the following directories:
Resource handler classes

src\package_name.rest.extension.resource_name.handler

Resource helper classes

src\package_name.rest.extension.bod.helpers

BOD mapping XML files

WebContent\WEB-INF\config\bodMapping-ext

Service client library XML file

WebContent\WEB-INF\config\bodMapping-ext

Resource properties file

WebContent\WEB-INF\config

Resource configuration XML file

WebContent\WEB-INF\config\com.ibm.commerce.rest-ext

Consuming the generated code
Perform the following steps to consume the generated code for customization:

Copy the rest-resource_name-clientobjects.xml file to the similar location under the Rest project in your workspace. Add additional XPath to attribute mappings for the noun we selected in the input XML file. The XPath is populated to the response data against the mapped attributes.
Copy the resources-ext.properties file to the similar location in the Rest project or merge the entries of files for the newly added resource handler class.
Copy the wc-rest-resourceconfig.xml file to the similar location in the Rest project. Create the WEB-INF\config\com.ibm.commerce.rest-ext folder if it does not already exist.
Copy the wc-service-client-library.xml file to the similar location in the Rest project or merge the entries of files for the newly added resource handler class.

Testing the customization

Restart the test server and invoke the URI for the newly added resource handler class.
The URI should resemble the following address: For a Get request (Person from the context):

http://host_name/wcs/resources/store/10101/person
For a Get request (Person with logon ID):

http://host_name/wcs/resources/store/10101/person/byLogonId/personID

Customizing and configuring REST resources using the BOD mapping framework
REST services are built on top of OAGIS services, and use an access profile and XPath to get data from an OAGIS noun. The access profiles used by REST services are defined in a configuration file by default. We can extend the configuration file to overwrite the data mapping.

Input file variable	Required	Description
component_name	Yes	The name of the component containing the Web service from which we want to create a REST service. If we are using an existing WebSphere Commerce service, obtain the component name by viewing the list in this topic: WebSphere Commerce Web services Examples of component names are: Catalog Marketing Order If we are creating a REST service from a custom WebSphere Commerce Web service, use the name of the component containing the custom Web service.
package_name_prefix	Yes	The prefix of the package containing the Java class output by this pattern. For a REST service from a WebSphere Commerce noun, use com.ibm.commerce For a REST service from a custom noun, use com.your_company_name.commerce, for example, com.mycompany.commerce
noun_name	Yes	The name of the noun to use to implement the REST service. To view nouns available for WebSphere Commerce components, see WebSphere Commerce Web services.
plural_noun_name	Yes	The plural form of the noun to use to implement the REST service. The convention is to specify the same singular value in a RESTful URL. For example, if a noun is Person, both noun_name and plural_noun_name should be set to be Person.
resource_name	No	The name of the REST resource we want to specify for a REST service.
action_expression	No	The action expression for the noun or its sub noun. For example: AddressBook/Contact.
action_expression_suffix	No	The action expression suffix for the noun or its sub noun. For example: [1].
default_access_profile	Yes	The name of the default storefront access profile to use for the WebSphere Commerce service request. The access profile defines the data to include in the response. Access profiles are defined for each noun in WebSphere Commerce Web services. Typically, storefront access profiles start with IBM_Store instead of IBM_Admin.
default_get_xpath_expression	No	The XPath expression for the GET service that gets all instances of a noun, rather than returning a specific instance of the noun by its identifier. Include this parameter in your pattern input file only if you need the JAX-RS resource to get all instances of a noun. For example, the Catalog noun has a GET XPath expression that gets all the sales catalogs for the store. In this case, the attribute in the pattern input file is: defaultExpression="/Catalog[@primary='false']" If your RESTful URL does not include an identifier, the JAX-RS resource uses the default_get_xpath_expression.
get_xpath_expression	Yes 1	The XPath expression for the GET service that gets a noun using the internal or external identifier you specified in the URL in the previous procedure. Example of an XPath expression that uses an internal identifier–Get Catalog service: /Catalog[CatalogIdentifier[(UniqueID=)]] This XPath expression gets a catalog by its unique ID and returns the catalog that matches the ID. Important: When we are including the XPath expression in the pattern input file, specify the following characters for the numeric UniqueID value, regardless of what is in the documented XPath expression: {0} The previous example XPath expression must look like the following string in the pattern input file: /Catalog[CatalogIdentifier[(UniqueID={0})]] Note: WebSphere Commerce does not provide a RESTful Web service for the Catalog noun, but you could create one using the procedures in this section. Example of an XPath expression that uses an external identifier–Get MarketingSpotData service: /MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=)]]] This XPath expression gets e-Marketing Spot data by its external identifier (in this case, its name) and returns the data for display to a customer. Important: When we are including the XPath expression in the pattern input file, if the identifier value is a string, specify the following characters for the string value, regardless of what is in the documented XPath expression: \"{0}\" The previous example XPath expression must look like the following string in the pattern input file: /MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=\"{0}\")]]]
findby_name	Yes 1	The suffix of the method name called when the URL contains an identifier. The pattern creates a method by using this suffix for the name. In the generated Java class, the full method name is findByfindby_name. The findby_name should match the identifier specified for the XPath expression for the Get service. For example, for the Get Catalog XPath expression in the previous row, an appropriate findby_name is Id.
get_access_profile	Yes 1	The name of the access profile to use for the WebSphere Commerce service get request. The access profile defines the data to include in the response.
key_to_delete	Yes 1	The unique key or identifier to delete a resource in a WebSphere Commerce service.
delete_method	Yes 1	The delete method of a WebSphere Commerce service client façade class, which takes Map as parameter. For example: MemberFacadeClient.deleteAddressForPerson(java.util.Map).
create_for	Yes 1	The resource to be created by using a WebSphere Commerce service.
create_method	Yes 1	The create method of a WebSphere Commerce service client façade class, which takes Map as parameter. For example: MemberFacadeClient.addAddressForPerson(java.util.Map).
update_for	Yes 1	The resource to be updated by using a WebSphere Commerce service.
update_method	Yes 1	The update method of a WebSphere Commerce service client façade class, which takes Map as parameter. For example: MemberFacadeClient.updateAddressForPerson(java.util.Map).