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.

Cortex Resource Representations

Cortex Resource Representations

You can use either the default Cortex plain JSON format or HAL format to view the current resource state. A Cortex instance can serve the default format and HAL format for different requests. You must change the settings in the Accept header to the required setting for each format to get responses in the required format.

Plain JSON Format

Cortex uses JSON to represent a resource's current state.

Cortex JSON representations use the following format:
  • A self object
  • A set of properties specific to the resource being represented
  • An array of links to other resources
Following is an example for a Cortex JSON representation:
{
  "self": {
    "type": {string},
    "uri": {string},  
    "href": {string}
  },
  "resource-property-1" : {string|number|object|array|true|false},
  ...
  "resource-property-n" : {string|number|object|array|true|false},
  "links": [
    {
      "rel": {string},
      "rev": {string},
      "type": {string},
      "uri": {string},
      "href": {string}
    },
    ...
    {
      "rel": {string},
      "rev": {string},
      "type": {string},
      "uri": {string},
      "href": {string}
    }
  ]
}

Plain JSON Format Properties

A self object returns with every JSON response with the following properties:

Property

Description
type The resource's type, which describes the properties the resource has.
uri The resource's Uniform Resource Identifier, which is a short string identifying the resource.
href The resource's hypertext reference, which is its fully qualified URL.

An array of links return with every JSON response. Links have a consistent order, so the client application need not sort the array. Each link has the following properties:

Property

Description

rel

The relationship name, which describes the relationship between this resource and the resource the link points to. This name is stable and will not change.

rev

The reverse relationship name, which describes the reverse relationship between this resource and linked to resource; in other words, the relationship from the linked resource to this resource. For example:

Revs

The rev is the only link property that is optional. If the rev is present and you follow the link, the linked resource will have a link back to the original resource. If the rev is not present and you follow the link, the linked resource will not have a link back to the original resource.
type The linked resource's type, which describes the properties the resource has.
uri The linked resource's Uniform Resource Identifier, which is a short string identifying the resource.

href

 The linked resource's hypertext reference, which is its fully qualified URL.

HAL Format

Cortex supports the standard HAL (Hypertext Application Language) format to represent hypermedia APIs. With the HAL format, the responses for large zoom queries are smaller. With every JSON response, a self object is returned with the following properties:

Property

Description
name The name of the resource that describes the property of the resource.
href The hypertext reference of the resource, which is its fully qualified URL.
Features
  • The links object in the default Cortex response is now changed to _links and the self object is another link within the _links.
  • The rel name is changed as the key in the _links object in HAL format. All rel objects with the same name are displayed in an array.
  • The type property of a link is now called name.
  • Each zoomed resource is nested within the _embedded object.

  • For each zoomed resource, the entity and the action links are returned. An action link accepts POST requests, such as addtodefaultcartaction. . Non-action links are not included in the responses as this information is not useful for the end users.

  • Self link is included if the format=zoom.noself option in the Setup header is disabled.

Following is an example for a response in HAL format: 
{
  "messages": [],
  "_links": {
    "self": {
      "name": "carts.line-items",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=/lineitems"
    },
    "element": [
      {
        "name": "carts.line-item",
        "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=/lineitems/gy3tayjvgrswmljxmu4taljuge4teljzg5rdoljqmi4tkm3fga4dmzbyha="
      },
      {
        "name": "carts.line-item",
        "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=/lineitems/mq2dmn3ehbstgljrhezwiljugq4gcllbgztdelldgmzggyrrgvrggmdcmu="
      }
    ],
    "cart": {
      "name": "carts.cart",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha="
    }
  }
}
Enabling Responses in HAL format

If the Accept header is set to application/json or is left blank, the Cortex responses uses the default format.

  • To enable HAL format, set the Accept header to application/hal+json.