Elastic Path Commerce Development

Links in JSON Responses

Links in JSON Responses

Links in Plain JSON Responses

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="
}

Links in the HAL responses

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="
    }