REST services are defined in Cortex by implementing the marker interface ResourceOperator

ResourceOperator methods handling a REST request must be annotated with both @Path and @OperationType and must return an OperationResult.

Cortex injects values into the parameters of each ResourceOperator method based on the type of the parameter and the method's annotations. An exhaustive list of annotations is available in the javadocs for the annotation package.

An example resource operator:

import com.elasticpath.rest.OperationResult;
import com.elasticpath.rest.resource.dispatch.operator.ResourceOperator;
import com.elasticpath.rest.resource.dispatch.operator.annotation.OperationType;
import com.elasticpath.rest.resource.dispatch.operator.annotation.Path;

@Path("/commerce-legacy/examples")
public class SimpleResourceExample implements ResourceOperator {

	@Path
	@OperationType(Operation.READ)
	public OperationResult processRead() {

		return OperationResult.Builder.builder()
				.build();
	}
}

The @OperationType annotation indicates which of the CRUD verbs (CREATE, READ, UPDATE, DELETE) a ResourceOperator method responds to.

OperationResults indicate to Cortex what ResourceState is being returned and whether the operation was successful or not. In addition to the HTTP status code, OperationResults can also return an error message describing why the operation was unsuccessful.

Create OperationResults with the builder method OperationResult.Builder.builder().

The @Path annotation specifies the uri that each method responds to. The uri for a specific method is derived from the @Path annotation of the class combined with the @Path of the method. For more details on @Path, see the @Path JavaDoc.

The ResourceState wraps a resource entity and provides readonly access to the entity's metadata such as the Self uri.

Create ResourceStates with the builder method ResourceState.Builder.create()

Cortex identifies entities such as orders, customers, items, searches, slots, navigations, and so on with IDs. To uniquely identify each domain object, the Elastic Path Commerce Engine assigns each object a Globally Unique IDentifier (GUID). Cortex provides a Base32Util utility for converting the GUIDs used by the Elastic Path Commerce Engine and to the encoded ids used in Cortex.

Create links between resources by implementing a ResourceStateLinkHandler. ResourceStateLinkHandler is a generic interface which should be typed to the resource you wish to link to. ResourceStateLinkHandler has one method, getLinks(). The getLinks() method receives a ResourceState that provides the meta data required to build the desired links, such as an item's id, and returns 0-many ResourceLinks in an iterable collection.

For example, to add links to item resources:

/**
 *  Adds a link to all ItemEntity objects returned by READ requests.
 */
public class CartToItemLinkHandler implements ResourceStateLinkHandler<ItemEntity> {
	public Iterable<ResourceLink> getLinks(ResourceState<ItemEntity>) {
		//method content returning links
	}
}

A ResourceLink represents a link to another resource. ResourceLinks are contained in ResourceStateLinkHandlers.

A resource being linked to does not need to know about the resource linking to it. For instance, in Writing Your First Resource, the Orders resource does not know about the Terms resource linking to it. This rule simplifies Cortex extension. When you add a new resource, you don't need to update all the existing resources to b aware of the new resource.

Create ResourceLinks with the builder method ResourceLink.Builder.builder(), similar to the following example:

ResourceLink.Builder.builder()
		.withRel("item")
		.withType(ItemMediaTypes.ITEM.id())
		.withUri("/commerce-legacy/sampleCartUri")
		.build();	

The MediaType is required by the link to define the type of the resource being linked to.

A MediaType identifies each resource by type and helps in deserializing a resource back into an object. Media types are also used when defining a link between resources, as seen in ResourceLink and ResourceStateLinkHandler. Media types are created by the api-generator-maven-plugin and take the form elasticpath.ResourceFamilyName.ResourceEntityName. For example, an items resource will have the MediaType elasticpath.items.item.