Legacy Implementation Strategies

With Elastic Path 7.4 release, the dispatch model or the legacy Cortex programming model is being deprecated and will not be supported in the future. For more information about the deprecation plan, see Dispatcher Deprecation Notice.

This section explains the patterns for use to implement and customize Cortex. Most resources use a combination of these patterns, which:

Take the guesswork of when/why/where/how to create new resources
Pair the business needs to an established pattern
Get building implementations using existing patterns rather than spending time designing/discovering your own patterns
Understand how the JSON representations and URIs connect to the pattern

Cortex Implementation Patterns

Resource Lookup - Retrieves a related set of data from your backend system through Cortex
Read From Other - Reads data from another resource
Link Strategy - Adds a link to a resource on another resource representation
Resource Update - Updates a resource status with data from a client application
Form - Provides customers with the ability to create something from information entered into a form. For example, creating an address for a profile, adding a cart to an order, adding an order to a purchase, or searching for items
Selector - Provides customers with the ability to make selections, such as selecting a billing address to use for an order, the options for an item, the payment means to use for an order, and so on

Resource Lookup

Problem: How do I surface up a single set of related data through Cortex API?

You have a set of related data you want to surface up to client applications through Cortex. For example, you have in-store promotions that alternate each day. Your store marketers change the promotions in their backend system and client developers need to display these promotions through their client applications.

If you were customizing another API, you would likely modify an existing resource that is related to promotions in order to surface up this data. However, this is a bad way to go about customizing a product. Elastic Path is continually updating the Cortex, so if you modify the default source code your Cortex will break when you upgrade. Also—and this is the main reason—modifying the default code to add some additional functionality to a resource defeats the purpose of Cortex design. Cortex is designed as a set of small independent resources to promote design qualities like cohesion (single responsibility) and to promote extension by composition. These designs help to maintain a clean/clear/consistent design over time as well as minimize the need to make breaking changes to the default code.

Solution: Create a new resource with the Resource Lookup (GET) pattern to retrieve a set of related data from your backend system and surface it through a single resource in Cortex.

Resource Lookup

Resource URI

Resource JSON Representation

Below is a JSON representation for a resource that uses the Resource Lookup (GET) pattern. The data is sparse in this example, but the idea is that this type of pattern returns a single set of related data. For example, the cart resource uses the Resource Lookup (GET) pattern to surface up cart data in a JSON representation.

When to Use

You want to surface a related set of data to a client application through a single resource.

Cortex Resources using this Pattern

Nearly every resource uses this pattern

Read From Other

The Problem: How to reuse an existing resource’s functionality in s new resource?

You want to reuse another resource’s functionality in your resource
You want a resource to depend on another resource
You want to keep your resource’s functionality granular

Cortex extension design methodology is to create new resources that augments existing behavior, not modify the default source code to get the required behavior.

Another problem you may experience is that you’re creating a resource that needs to depend on another resource. Take for instance, the totals resource. This resource depends on other resources to function. For example, totals uses an RFO to read lineitems in a cart, then calculates the total cost of the items in the cart.

The Solution: Read From Other(RFO) - Create a new resource with the RFO pattern to read data from another resource.

Read From Other

With a RFO, you don’t need to reinvent the wheel with your resources. The RFO can retrieve data from another resource, so you don’t have to build out that functionality.

The RFO pattern can also help keep your resource functionality granular. Take for instance the availabilities and items resources. The availabilities resource uses an RFO to read an item, get its ID and scope, then uses those details to retrieve the item availability from the back end system. This is opposed to having one resource that does these two separate responsibilities. With granularity like this you can replace the availabilities resource with a custom resource that interacts with another back end system without it affecting the items resource.

Resource URI

The resource URI, identified at the end of the URI, gets the profiles representation. The extensionprofile resource consumes the profiles representation and then surfaces its representation.

Resource JSON Representation

Below is the JSON representation for the extensionprofile, which uses the RFO pattern. The extensionprofile resource reads the profiles resource’s representation and then creates its own representation from the data. In the example below, the family-name and given-name have been read from the profiles resource, added to the extensionprofile’s representation, and then surfaced up to the client application along with the profileId. In this way, the profile’s resources functionality has been extending without changing the default code for profiles.

{
    "self": {
         "type": "application/vnd.mycompany.extensionprofile",
         "href": "https://localhost:8443/cortex/extensionprofile/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq",
         "uri": "/extensionprofile/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq"
    },
    "familyName": "Harris",
    "name": "Oliver",
    "profileId": "gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq",
    "links": [
        {
            "type": "elasticpath.profiles.profile",
            "rel": "profile",
            "rev": "extensionprofile",
            "href": "https://localhost:8443/cortex/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq",
            "uri": "/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq"
        }
    ]
}

When to use

Reuse an existing resource’s data in your resource - For example, the rates resource uses an RFO to read the items resource’s ID and scope to retrieve in order to retrieve the item’s cost and billing frequency.

Cortex Resources using this Pattern

availabilities - Uses an RFO to read a cart’s lineitems and then surface up the lineitem’s availability
prices - Uses an RFO to read a cart’s lineitems and then retrieve the promoted prices for the item
totals - Uses an RFO to read the items in a carts lineitems and then surfaces up the total cost of the items in the cart

Link Strategy

The Problem: How to link the resources that is being built to related default resources or other customized resources?

You want to connect the resource that you build with another resource, but cannot use RFO.

The Solution: Create a resource that adds a link to itself on another resource’s representation.

Link Strategy

Cortex recommendations resource is a crosscutting resource that provides functionality to the items and navigations resources. The recommendations resource uses a Link Strategy to attach links to the items and navigation resources. Using these links, client applications can follow them to see recommended products for specific items and navigations.

When you use link strategy, you need not modify the resource you’re linking to. The links are attached dynamically so the resource being linked to doesn’t even know it has a link. This is Cortex’s secret admirer rule. This way you can build out relationships without having to worry about code upgrade paths.

Resource URI

Resource JSON Representation

Below is the JSON representation for the profiles representation.

{
    "self": {
        "type": "elasticpath.profiles.profile",
        "href": "https://localhost:8443/cortex/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq",
        "uri": "/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq"
    },
    "family-name": "Harris",
    "given-name": "Oliver",
    "links": [
        {
            "type": "elasticpath.collections.links",
            "rel": "addresses",
            "rev": "profile",
            "href": "https://localhost:8443/cortex/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq/addresses",
            "uri": "/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq/addresses"
        },
        {
            "type": "elasticpath.collections.links",
            "rel": "paymentmethods",
            "rev": "profile",
            "href": "https://localhost:8443/cortex/paymentmethods/mobee",
            "uri": "/paymentmethods/mobee"
        },
        {
            "type": "application/vnd.mycompany.extensionprofile",
            "rel": "extensionprofile",
            "rev": "profile",
            "href": "https://localhost:8443/cortex/extensionprofile/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq",
            "uri": "/extensionprofile/profiles/mobee/gy3ukmrygbaugljxiu4dmljtgjatgljvhfbdeljwgeyemrrsinatgoceiq"
        },
        {
            "type": "elasticpath.collections.links",
            "rel": "purchases",
            "href": "https://localhost:8443/cortex/purchases/mobee",
            "uri": "/purchases/mobee"
        }
    ]
}

Cortex Resources using this Pattern

lineitems - Creates a link to the cart’s representation
orders - Creates links to the purchase, carts, deliveries, and billinginfo representations
recommendations - Adds links to items and navigations
addresses - Adds a link to a profile
search - Adds links to keyword search and offer search

When to Use

Link resources to other related resources.

Resource Update

The Problem: How do I update a resource with data from a client application?

You need to update a resource with data from a client application.

Often, client applications need to update a resource data based on information provided by the client application. Changing an address, password, profile, and so on, are all examples of updating data.

The Solution: Resource Update - Create a resource that updates its state with data from a client application.

Resource Update

Resources can accept PUT requests from client applications and execute write requests to update the data in the backend system.

Resource URI

Resource JSON Representation

Below is the address JSON object that will be sent to the addresses resource.

{
    "address": {
        "country-name": "CA",
        "locality": "Richmond",
        "postal-code": "V6qE4s",
        "region": "BC",
        "street-address": "14300 Riverport",
        "street-address-2": "",
        "street-address-3": ""
    },
    "name": {
        "family-name": "Tiger",
        "given-name": "Tom"
    }
}

Cortex Resources using this Pattern

lineitems - Accepts a PUT request to update the quantity of items in the lineitem
profiles - Accepts a PUT request to update the customer profile data
addresses - Accepts a PUT request to update address details

When to Use

You want to update a resources state with data from the client application.

Reference Example

Look at lineitems, profiles, and the addresses resources.

Form

The Problem: How do I create data in the Cortex API?

You need a way for client applications to create data in Cortex.

A common problem is enabling client applications to create data in Cortex. For example, creating a new customer, a new address or a new payment method.

The Solution: Create a resource with a form to provide customers with the ability to create something in the Cortex from the data they’ve entered in a form.

Form

Cortex uses forms to create data. For example, creating an address for a profile, creating a new customer, adding a cart to an order, or adding an order to a purchase. Client Applications GET the form, fill out the form’s details based of customer input, and then POST the filled out form to the form’s actionlink to create the data.

Resource URI

The form identifier is a Cortex standard used to indicate a form returns from the request.

Resource JSON Representation

Below is the addresses form JSON representation, containing the action link to POST the form to.

{
    "self": {
        "type": "elasticpath.addresses.address",
        "uri": "/profiles/<scope>/<profileid>/addresses/form",
        "href": "http://www.onlinestore.com/profiles/<scope>/<profileid>/addresses/form"
    },
    "links": [
        {
            "rel": "createddressaction",
            "href": "http://www.onlinestore.com/profiles/<scope>/<profileid>/addresses",
            "uri": "/profiles/<scope>/<profileid>/addresses"
        }
    ],
    "address": {
        "country-name": "",
        "locality": "",
        "postal-code": "",
        "region": "",
        "street-address": "",
        "street-address-2": "",
        "street-address-3": ""
    },
    "name": {
        "family-name": "",
        "given-name": ""
    }
}

Cortex Resources using this Pattern

address - Returns a form to create a new address for a customer
orders - Returns a form to submit the order to a purchase
search - Returns a keyword search form and an offer search form to submit the search keyword to the search resource
registration - Returns a form to submit to the registration resource to create a new customer
profiles - Returns an email form allowing customers to create emails for their profile

When to Use

You need a customer’s input to perform an action, such as creating a new customer or billing address, making a purchase, adding a credit card to their payment, or performing a search.

Reference Example

orders - Uses a form as well as needinfos to ensure a customer has selected their billing address, payment method, and if necessary their shipping address and options.

Selector

The Problem: How do I allow customers to make choices through the Cortex API?

You need to provide a way for customers to make selections in the Cortex. For example: - Selecting a color for an item in the store that is available in red, blue, or green - Selecting a shipping options, such as FedEx, Canada Post, or Purolator

The Solution: Create a resource with a selector to provide customers with the ability to make selections, such as choosing a billing address, shipping option, a payment method, or item options.

Selector

Cortex uses selectors

Resource URI

The selector identifier is a Cortex standard used to indicate a selector returns from the request.

Resource JSON Representation

Below is the JSON destinationinfo selector. Customers GET their choice, then post to the select action rel of the choice to make the selection.

{
    "self": {
        "type": "elasticpath.controls.selector",
        "uri": "/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector",
        "href": "www.onlinstore.com/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector"
    },
    "links": [
        {
            "type": "elasticpath.collections.links",
            "rel": "chosen",
            "rev": "selector",
            "href": "www.onlinstore.com/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector/profiles/<scope>/<profileID>/addresses/<addresseID>",
            "uri": "/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector/profiles/<scope>/<profileID>/addresses/<addresseID>"
        },
        {
            "type": "elasticpath.collections.links",
            "rel": "choice",
            "rev": "selector",
            "href": "www.onlinstore.com/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector/profiles/<scope>/<profileID>/addresses/<addresseID>",
            "uri": "/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo/selector/profiles/<scope>/<profileID>/addresses/<addresseID>"
        },
        {
            "type": "elasticpath.controls.info",
            "rel": "destinationinfo",
            "rev": "selector",
                "href": "www.onlinstore.com/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo",
                "uri": "/orders/<scope>/<orderID>/deliveries/<deliveryID>/destinationinfo"
        }
    ],
    "name": "destination-selector",
    "selection-rule": "1"
}

Cortex Resources using this Pattern

itemselections - Provides a selector to select item options
shipmentdetails - Provides a selector to select the orders shipping option, such as Canada Post or FedEx, and a selector to select the destination address
orders - provides a selector to select the billing address of the order
paymentmethods - Provides a selector to select the payment method to use for the purchase

When to Use

You want to provide customers with the ability to make selections, such as select an options of an item, the billing addresses for the order, shipping addresses, and payment means.

Reference Example

shipmentdetails resource - provides selectors to select the order’s shipping option and destination address.