Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Writing Your First Resource

Writing Your First Resource

Warning: Before you begin

Make sure your development environment has been properly set up as described in Setting up your Developer Environment.

In this tutorial, you will learn how to:
  • Create a resource, called terms and conditions, that returns a simple message: "An example terms and conditions string"
  • Write a unit test that will help you troubleshoot basic problems with your resource.
  • Add this resource to your Cortex web application.

When this tutorial is complete, you can retrieve the message by sending the following request to Cortex with Cortex Studio or another REST client:

Cortex Studio Request:
/terms/12345=
Response: 
{
  "self": {
    "type": "{vendor}.terms.terms-and-conditions",
    "uri": "/commerce-legacy/terms/12345=",
    "href": "http://localhost:9080/cortex/terms/12345=",
    "max-age": 0
  },
  "links": [],
  "message": "An example terms and conditions string"
}

Defining the API

To create the terms and conditions resource, you first need to create a definitions XML called terms-and-conditions-api.xml. Later,we will generate the terms and conditions resource Java code from this definitions XML by using the resource-api generator.

Below is an example of the terms-and-conditions-api.xml you will create in this section: 
<?xml version="1.0"?>
<definitions xmlns="http://www.elasticpath.com/schema/rest/0.1">

	<resource-family>
		<name>terms</name>
		<description><![CDATA[Terms resource.]]></description>

		<entity>
			<name>terms-and-conditions</name>
			<description><![CDATA[Defines the Terms And Conditions resource entity.]]></description>

			<property>
				<name>terms-id</name>
				<description><![CDATA[The identifier representing each individual entity.]]></description>
				<internal/>
				<string/>
			</property>

			<property>
				<name>message</name>
				<description><![CDATA[The terms and conditions text.]]></description>
				<string/>
			</property>

			<entity-type>training.terms.terms-and-conditions</entity-type>
		</entity>
	</resource-family>

</definitions>
Key elements in the definitions XML:
  • <resource-family> - Defines the resource family the resource belongs to. A resource family is a way to group related resources. For example, carts is a resource family, which the line-items resource, a subcomponent of carts, belongs to.
  • <entity> - Defines the resource and its properties.
  • <name> - Defines the resource's name.
  • <property> - Defines the resource's properties. There are two properties in the example:
    • <name>terms-id</name> - Stores a unique identifier for the resource.
    • <name>message</name> - Stores the terms and conditions message.
  • <entity-type> - Defines the resource's type. Client developer use types to identify the JSON object returned by Cortex. i.e. cart, price, and so on.
To create the terms-and-conditions-api.xml:
  1. Open a command line and navigate to the extensions/tutorials directory.
  2. Run the following command to create a Cortex resource API definition project: 
    mvn clean package -Dtheme=cortex -Dpatch=generators/resource-api -Dproperties="resourceVendor=training,resourceFamily=terms,resourceEntity=termsAndConditions"
  3. In your IDE, open the extensions/cortex/resources-api/terms-and-conditions-api project.
  4. In terms-and-conditions-api.xml:
    1. Re-name the property entity-value to message
    2. Change the description to <![CDATA[The terms and conditions text.]]>.

Generating the API Jar

Now that you've created an API definition, use the API generator maven plugin to create a jar containing the classes required to implement the terms and conditions resource.

  1. Open a command line and navigate to the terms-and-conditions-api project
  2. Run the following command to build the API definition:
    mvn clean install
    Source files generate to: target/generated-sources/api-generator and are packaged in the terms-and-conditions-api-<version>.jar. Take a look at TermsAndConditionsEntity.java, as you will use this class later in the tutorial.

Implementing the Resource

You will now create the resource implementation using the resource-impl generator.

  1. Open a command line and navigate to the extensions/tutorials directory.
  2. Run the following command to create the Cortex resource implementation project: 
    mvn clean package -Dtheme=cortex -Dpatch=generators/resource-impl -Dproperties="resourceFamily=terms,resourceEntity=termsAndConditions"
  3. In your IDE, open the extensions/cortex/resources/terms-and-conditions-resource project.
  4. Fix the compilation errors in TermsResourceOperatorImpl.java and TermsResourceOperatorImplTest.java that are a result of changing the entity-value field to message in the resource API XML. Method names in resource operators correspond to the property names in the API. Since you changed the property entity-value to message, the corresponding method names also need to be updated.
  5. In TermsResourceOperatorImpl.java change the returned message text to "An example terms and conditions string".
  6. Following these changes the TermsAndConditionsEntity.Builder code in TermsResourceOperatorImpl.java should look like:
    TermsAndConditionsEntity entity = TermsAndConditionsEntity.Builder.builder()
	.withTermsId(termsId)
	.withMessage("An example terms and conditions string")
	.build();
  7. Fix the failing unit test in TermsResourceOperatorImplTest.java.
  8. Open a command line, navigate to extensions/cortex/resources/terms-and-conditions-resource, and the following command to build the terms and conditions resource JAR file and execute the unit tests:
    mvn clean install

Testing the Resource

At this point, you've created all the necessary components for the terms and conditions resource and the final result can be verified.

  1. Open a command line and navigate to the extensions/cortex/ext-cortex-webapp directory.
  2. Run the following command to build and run the Cortex web application:
    mvn clean tomcat7:run-war
  3. Open Cortex Studio in a browser at http://localhost:9080/studio/ and submit a GET Request for:
    /terms/12345=
    Response:
    {
  "self": {
    "type": "{vendor}.terms.terms-and-conditions",
    "uri": "/commerce-legacy/terms/12345=",
    "href": "http://localhost:9080/cortex/terms/12345=",
    "max-age": 0
  },
  "links": [],
  "message": "An example terms and conditions string"
}
    Congratulations, you’ve just built your first Cortex resource. Next, in Adding Links to Your Resource, you will learn how to link the orders resource to your resource so a client can view the terms and conditions from an order.