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.

Creating Cortex API Resources

Creating Cortex API Resources

Elastic Path provides a Maven Archetype (rest-resource-extension-archetype) to simplify the programmer's job of creating new Cortex API resources. New resources must be added to the Cortex API's resource-extensions-configuration-blueprint.xml so the Cortex API can be aware of them, see Adding new resources to the Resource Layer for more information.

Note: Before You Begin

Make sure that your developer environment, including the local Maven repository, is set up as described in Setting up your Developer Environment.

  1. Open a command prompt and navigate to your Extensions Directory.
  2. Run the following command to create a Cortex API Resource Extension project:
    mvn archetype:generate -DarchetypeArtifactId=rest-resource-extension-archetype -DarchetypeGroupId=com.elasticpath.rest.archetype -DarchetypeVersion=<your-artifact-version>
    Tip: Stack Trace Tip

    You may see a stack trace preceded by a warning similar to the following:

    [WARNING] Error reading archetype catalog http://repo1.maven.org/maven2
org.apache.maven.wagon.TransferFailedException: Error transferring file: Connection timed out: connect

    This can occur if you are operating Maven in online mode. It can be safely ignored.

  3. Enter the following information when prompted:
    Table 1.
    Variable Value
    groupId The group ID of your company
    artifactId The artifact ID you want to use for the project
    version The version of the archetype artifact
    package The base Java package structure of the customization (defaults to the groupId)
    Note: Artifact and Group ID Note

    Your artifactId must not include your groupId. If your groupId is com.example, your artifactId cannot be com.example.extension

  4. Change to the newly created project directory and execute the following command to build the Cortex API resource JAR file:
  5. Execute the Maven build command:
    mvn install
    Tip: Remove Build Artifacts Tip

    If you want to remove previous build artifacts before rebuilding, use mvn clean install instead.

Next steps

Adding new resources to the Resource Layer

New resources must be added to the Cortex API's resource-extensions-configuration-blueprint.xml so OSGi can register the new resource bundle and load it in the Cortex API web application. You also need to add the new resource to the Cortex API web application's POM as a dependency.

  1. In the Cortex API Resource-Configuration project generated in Generate the Cortex API Resource-Configuration Project, add the new resource bundle's Bundle-Symbolic Name to the resource-configuration-blueprint.xml.
    For example, if the new resource's Bundle-Symbolic Name was com.elasticpath.dcapi.example.cortex-resource-helloworld, the resource-configuration-blueprint.xml would look like this:
    <blueprint
		xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">
	<!-- export services -->
	<service id="requiredResourceServerBundles" interface="java.util.List">
		<bean class="java.util.ArrayList">
			<argument>
				<array value-type="java.lang.String">
					...
					<value>com.elasticpath.rest.example.rest-resource-helloworld</value> 
					...
				</array>
			</argument>
		</bean>
	</service>
</blueprint>
  2. In your Cortex API web application pom.xml, add the resource as a <dependency> and an <artifactitem>. For example, 
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
 
    <parent>
        <groupId>com.elasticpath.cortex.dce</groupId>
        <artifactId>cortex-dce-parent</artifactId>
        <version>0.1.0-SNAPSHOT</version>
    </parent>
 
    <groupId>com.elasticpath.cortex.dce</groupId>
    <artifactId>ep-cortex-dce-webapp</artifactId>
    <version>0.1.0-SNAPSHOT</version>
    <packaging>war</packaging>
    <name>EP -- Cortex DCE REST Webapp</name>
    <description>Elastic Path Cortex DCE Web Application</description>
 
    <!-- webapp -->

	<dependencies>
...
	<!-- Resource Servers -->
	<dependency>
            <groupId>com.elasticpath.rest.example</groupId>
            <artifactId>rest-resource-helloworld</artifactId>
            <version>0.1.0-SNAPSHOT</version>
            <scope>provided</scope>
    </dependency>
...
 
<plugins>
            <!-- copy OSGi bundles into WEB-INF/bundles -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <executions>
                    <execution>
                        <id>copy-OSGi-bundles</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>copy</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${war-bundle-directory}</outputDirectory>
                            <artifactItems>
                              ...
                                <artifactItem>
                                    <groupId>com.elasticpath.rest.example</groupId>
                                    <artifactId>rest-resource-helloworld</artifactId>
                                </artifactItem>
...
  3. Rebuild, mvn install, the Cortex APIapplications in this order:
    1. Cortex API Resource-Configuration project
    2. Cortex API web application.
  4. Run the Cortex API web application, see 3. Running Cortex API.

rest-resource-extension-archetype Components

The rest-resource-extension-archetype allows developers to quickly get started building resources to expand the Cortex API's functionality. The instructions on how to create a custom resource project from this Archetype are described in Creating Cortex API Resources. This rest resource archetype comes with a number of example components. The section below describes these components.

<rest-resource-extentsion-archetype>
|--src
|----main
|------java
|--------com
|----------elasticpath
|------------rest
|--------------resource
|----------------example
|------------------impl
|----------------------ExampleResourceOperatorImpl.java //Processes the resource operation for the example.
|------------------rel
|----------------------ExampleResourceRels.java // Defines the REL and REV for the example.
|------------------ExampleMutator.java //Creates the resource representation and sets the representation's properties
|--------------schema
|----------------representation
|----------------------ExampleRepresentation.java //Mutator for modifying the Example representation.
|------resources
|--------OSGI-INF
|----------blueprint
|------------example-blueprint.xml //Defines this example resource's OSGi configuration 
|------------springCtx-import.xml //Tells OSGi where to find the spring configuration for this project.
|--------spring
|----------applicationContext-resource-permissions.xml //Defines this resource's access permissions for each user role.
|----------applicationContext-resource-server.xml //Defines this resource's resource server.
|----test
|------java //Contains test classes
|--target
|--pom.xml

Standard Resource Components

This section is designed to give you an idea of the standard components found in an out-of-the-box Cortex API resource. Not every resource has all these files and directories. 

<artifact_id>
|--src
|----main
|------java
|--------com
|----------elasticpath
|------------dcapi
|--------------resources
|----------------<resource_name>
|------------------Lookup.java
|------------------Mutator.java //Creates the resource representation and sets the representation's properties
|------------------Writer.java
|------------------command
|--------------------CreateCommand.java
|--------------------ReadCommand.java
|--------------------UpdateCommand.java
|--------------------DeleteCommand.java
|--------------------impl
|----------------------LinkStrategy.java //Implements how links to the resources are inserted in other resources
|----------------------CreateCommandImpl.java //Implements how the resource handles a Create operation
|----------------------ReadCommandImpl.java //Implements how the resource handles a Read operation
|----------------------UpdateCommandImpl.java //Implements how the resource handles an Update Operation
|----------------------DeleteCommandImpl.java //Implements how the resource handles a Delete operation
|------------------impl
|--------------------LookupImpl.java //Implements how the resource reads data from an ecommerce system
|--------------------ResourceOperatorImpl.java //Manages the requests the resource resource receives
|--------------------UriBuilderImpl.java //Builds the URI to the specific cart / item / profile
|--------------------UriBuilderFactoryImpl.java
|--------------------WriterImpl.java //Implements how the resource writes data to an ecommerce system
|------------------integration
|--------------------DTO.java //Defines a data transfer object for transferring data from the Elastic Path Core
|--------------------LookupStrategy //Implements how the lookup from the Elastic Path Core is handled
|--------------------WriterStrategy //Implements how the write to the Elastic Path Core is handled
|------------------permissions
|--------------------ParameterStrategy.java //Resolves the permission parameters the resource receives.
|------------------<subresource_name> //Contains the subresource's implementation.
|------------------rel
|--------------------ResourceRels.java //Defines the resource's identifiers
|------------------transform
|--------------------Transformer.java //Converts the data from an ecommerce system into a resource representation
|------------------validator //Contains the resource's validators
|------resources
|--------OSGI-INF
|----------blueprint
|------------blueprint.xml //Defines the resource's OSGi configuration
|--------spring
|----------applicationContext-resource-permissions.xml //Defines test resource's permissions for each user role
|----------applicationContext-resource-server.xml //Defines the resource's Java Beans
|----test
|------java //Contains test classes
|--target
|--pom.xml