Skip to main content
Version: 7.6.x

Resource Representation

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:

  • 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:

  • 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:

    rev property explanation

    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

Cortex uses hypermedia links to associate related resources. Links have a relationship name, or rel that defines the relationship a resource has with other resources. Unlike URLs, which may change as the API evolves, these relationship names are stable and will not change. Using rels to link to resources provides the following advantages:

  • New relationships and features added to Cortex do not affect your application

    Either use the new links in your application or safely ignore them.

  • A single Cortex can power different types of client applications

    Each application can choose to use a different subset of links, which is important for mobile applications as they may not want to display as much detail as a web application.

  • Using rels effectively decouples your client application from Cortex

Links return in an array with every resource request. The following example shows a cart resource’s links array:

"links": [
  {
    "rel": "lineitems",
    "rev": "cart",
    "type": "elasticpath.collections.links",
    "uri": "/carts/mobee/guz=/lineitems",
    "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems"
  },
  {
    "rel": "order",
    "rev": "cart",
    "type": "elasticpath.orders.order",
    "uri": "/orders/mobee/mu3=",
    "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3="
  },
  {
    "rel": "total",
    "rev": "cart",
    "type": "elasticpath.totals.total",
    "uri": "/totals/carts/mobee/guz=",
    "href": "http://api.elasticpath.net:8080/cortex/totals/carts/mobee/guz="
  }
]

A link to the resource itself returns with every request. The self link is contained within a self object that describes the retrieved resource. This following example shows a cart resource’s self object:

"self": {
  "type": "elasticpath.carts.cart",
  "uri": "/carts/mobee/guz=",
  "href": "http://api.elasticpath.net/cortex/carts/mobee/guz="
}

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:

  • 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.

Links in the HAL responses serve the same purpose as in Plain JSON responses. For HAL responses, the links object in the Plain JSON response is _links and the self object is another link within the _links object.

The _links objects return an array with every resource request. The following example shows a cart resource’s _links array:

"_links": {
    "self": {
      "name": "carts.cart",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha="
    },
    "lineitems": {
      "name": "carts.line-items",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=/lineitems"
    },
    "discount": {
      "name": "discounts.discount-for-cart",
      "href": "http://api.elasticpath.net/cortex/discounts/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha="
    },
    "order": {
      "name": "orders.order",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/he2dimjygmzwcllemuydaljuhe2tkljymrtgellbhbrtazjtgi4dinleg4="
    },
    "appliedpromotions": {
      "name": "promotions.applied-promotions-for-cart",
      "href": "http://api.elasticpath.net/cortex/promotions/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=/applied"
    },
    "total": {
      "name": "totals.cart-total",
      "href": "http://api.elasticpath.net/cortex/totals/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha="
    }
}

The self object is a link within the _link object. The following example shows the self object in a response:

"_links": {
    "self": {
      "name": "carts.cart",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha="
    }
}
Last updated on