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 hasuri
: The resource’s Uniform Resource Identifier, which is a short string identifying the resourcehref
: 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:
The
rev
is the only link property that is optional. If therev
is present and you follow the link, the linked resource will have a link back to the original resource. If therev
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
Links in Plain JSON Format
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 rel
s 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
rel
s 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 resourcehref
- 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 theself
object is another link within the_links
- The
rel
name is changed as the key in the_link
s object in HAL format. Allrel
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 asaddtodefaultcartaction
. 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 HAL Format
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="
}
}