Elastic Path Commerce Development

Zoom

Zoom

Cortex uses hypermedia links to associate related resources together. Client applications need to make multiple requests to retrieve information from a resource's links. Using zoom, you can retrieve all these links with a single request. When a request uses zoom, Cortex retrieves all the requested links and generates a single response containing the linked data. All links that can be retrieved can also be "zoomed".

Zoom Basics

Add Zoom to as a query parameter to any request. Commas and colons separate the zoom parameters. For example, the following request retrieves a cart resource and the cart's total (?zoom=total) and the price for each item in the cart (lineitems:element:item:price)
http://api.elasticpath.net/cortex/carts/mobee/default?zoom=total,lineitems:element:item:price

The linked resources are appended to the response as nested arrays:

self
links
_lineitems
  _element
    _item
      _price
_total      
Zoomed responses have the following characteristics:
  • The links are always returned as arrays as multiple links with the same rel may exist.
  • The zoom arrays are prefixed with an underscore _ to indicate that the field was added by a zoom request.
  • The zoom arrays are ordered and nested according to the order of the resource's links, not the order of the zoom parameters. For example, the response from ?zoom=total,lineitems:element:item:price will order lineitems before totals:
    self
    links
    _lineitems 
      _element 
        _item 
          _price
    _total                
  • The self URI of the response includes the zoom query string to indicate that the request was zoomed.

Zoom Syntax

Zoom syntax is comprised of rels and paths. A rel is a link to retrieve and a path is a set of rels to follow. For example:

  • rel: ?zoom=rel1,rel2
  • path: ?zoom=rel:rel:rel
Rels and paths are separated by the following characters:
Table 1.
Character Description
, Separates paths to follow
: Identifies the rel of links to retrieve
Zoom requests with correct syntax will return a response without an error even if the rel or path does not exist. This means zoom requests will not return an error in the following situations:
  • When a rel is misspelled. For example: profiles/mobee/default?zoom=misspeltlink returns without error.
  • When a rel doesn't exist. For example: profiles/mobee/default?zoom=addresses:notarel returns without error.
  • When a request is partially valid. For example: profiles/mobee/default?zoom=addresses,notarel) returns without error.
If the zoom syntax is incorrect, a 400 Bad Request returns with an error message. Zoom requests will return an error in the following situations:
  • A rel or path is missing. For example ?zoom=,, returns an error.
  • A rel or path contains non-supported characters. This includes spaces, control characters, and unsafe URI characters, For example: $ & + , / : ; = ? @ < > # % { } | \ ^~ [ ] ` ' " returns an error.
  • The zoom length is greater than to 2048 characters.
  • A zoom path is nested 10 levels or deeper. For example, ?zoom=rel1:rel2:rel3:rel4:rel5:rel6:rel7:rel8:rel9:rel10:rel11 returns an error.
  • There is no restriction of the number of paths that can be requested. For example, ?zoom=path1,path2,path3,path4,path5,path6,path7,path8,path9,path10,path11, is allowed

Example: Retrieve Linked Resources

This example shows how zoom can retrieve a cart resource's lineitems and total links.

{
  "self": {
    "type": "elasticpath.carts.cart",
    "uri": "/carts/mobee/guz=",  
    "href": "http://api.elasticpath.net/cortex/carts/mobee/guz="
  },
  "total-quantity" : 3,
  "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="
    }
  ]
}

This zoom request retrieves a cart's corresponding lineitems and total resources:

GET /carts/mobee/guz=?zoom=total,lineitems

Cortex returns a single JSON response with the lineitems and total resources in arrays. Array property names are prefixed with an underscore to indicate they were added by a zoom request:

{
  "self": {
    "type": "elasticpath.carts.cart",
    "uri": "/carts/mobee/guz=?zoom=lineitems,total",
    "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=?zoom=lineitems,total"
  },
  "total-quantity": 3,
  "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/cortex/totals/carts/mobee/guz="

    }
  ],
  
  "_lineitems": [
    {
      "self": {
        "type": "elasticpath.collections.links",
        "uri": "/carts/mobee/guz=/lineitems",
        "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems"
      },
      "links": [
        {
          "rel": "element",
          "rev": "list",
          "type": "elasticpath.carts.line-item",
          "uri": "/carts/mobee/guz=/lineitems/hfq=",
          "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems/hfq="
        },
        {
          "rel": "element",
          "rev": "list",
          "type": "elasticpath.carts.line-item",
          "uri": "/carts/mobee/guz=/lineitems/gbq=",
          "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems/gbq="
        },
        {
          "rel": "cart",
          "rev": "lineitems",
          "type": "elasticpath.carts.cart",
          "uri": "/carts/mobee/guz=",
          "href": "http://api.elasticpath.net/cortex/carts/mobee/guz="
        }
      ]
    }
  ],
  "_total": [
    {
      "self": {
        "type": "elasticpath.totals.total",
        "uri": "/totals/carts/mobee/guz=",
        "href": "http://api.elasticpath.net/cortex/totals/carts/mobee/guz="
      },
      "cost": [
        {
          "amount": 211,
          "currency": "CAD",
          "display": "$211.00"
        }
      ],
      "links": [
        {
          "rel": "cart",
          "rev": "total",
          "type": "elasticpath.carts.cart",
          "uri": "/carts/mobee/guz=",
          "href": "http://api.elasticpath.net/cortex/carts/mobee/guz="
        }
      ]
    }
  ]
  
}

Example: Retrieve Nested Linked Resources

This example shows how zoom can retrieve linked resources and linked child resources. The example retrieves a cart's lineitems and total resources and nested lineitem resources. lineitem resources are linked child resources of the lineitems resource.

{
  "self": {
    "type": "elasticpath.carts.cart",
    "uri": "/carts/mobee/guz=",  
    "href": "http://api.elasticpath.net/cortex/carts/mobee/guz="
  },
  "total-quantity" : 3,
  "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="
    }
  ]
}

The linked lineitems resource has two links called element. Each element refers to a lineitem in the cart:

{
  "self": {
    "type": "elasticpath.collections.links",
    "uri": "/carts/mobee/guz=/lineitems",
    "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems"
  },
  "links": [
    {
      "rel": "element",
      "rev": "list",
      "type": "elasticpath.carts.line-item",
      "uri": "/carts/mobee/guz=/lineitems/hfq=",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems/hfq="
    },
    {
      "rel": "element",
      "rev": "list",
      "type": "elasticpath.carts.line-item",
      "uri": "/carts/mobee/guz=/lineitems/gbq=",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems/gbq="
    },
    {
      "rel": "cart",
      "rev": "lineitems",
      "type": "elasticpath.carts.cart",
      "uri": "/carts/mobee/guz=",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/guz="
    }
  ]
}

This zoom request retrieves the cart resource's corresponding lineitems and total resources and each nested lineitem resource:

GET /carts/mobee/guz=?zoom=total,lineitems:element

Cortex returns a single JSON response with the lineitems, total, and lineitem resources in arrays. Each lineitem resource is a nested object inside the lineitems array. Array property names are prefixed with an underscore to indicate they were added by a zoom request:

{
  "self": {
    "type": "elasticpath.carts.cart",
    "uri": "/carts/mobee/guz=?zoom=lineitems:element,total",
    "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=?zoom=lineitems:element,total"
  },
  "total-quantity": 3,
  "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/cortex/totals/carts/mobee/guz="
    }
  ],  
  
  "_lineitems": [
    {
      "_element": [
        {
          "self": {
            "type": "elasticpath.carts.line-item",
            "uri": "/carts/mobee/guz=/lineitems/hfq=",
            "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems/hfq="
          },
          "quantity": 2,
          "links": [
            {
              "rel": "item",
              "type": "elasticpath.items.item",
              "uri": "/items/mobee/m5yx=",
              "href": "http://api.elasticpath.net/cortex/items/mobee/m5yx="
            },
            {
              "rel": "cart",
              "type": "elasticpath.carts.cart",
              "uri": "/carts/mobee/guz=",
              "href": "http://api.elasticpath.net/cortex/carts/mobee/guz="
            },
            {
              "rel": "list",
              "type": "elasticpath.collections.links",
              "uri": "/carts/mobee/guz=/lineitems",
              "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems"
            },
            {
              "rel": "availability",
              "rev": "lineitem",
              "type": "elasticpath.availabilities.availability",
              "uri": "/availabilities/carts/mobee/guz=/lineitems/hfq=",
              "href": "http://api.elasticpath.net/cortex/availabilities/carts/mobee/guz=/lineitems/hfq="
            },
            {
              "rel": "price",
              "rev": "lineitem",
              "type": "elasticpath.prices.item-price",
              "uri": "/prices/carts/mobee/guz=/lineitems/hfq=",
              "href": "http://api.elasticpath.net/cortex/prices/carts/mobee/guz=/lineitems/hfq="
            }
          ]
        },
        {
          "self": {
            "type": "elasticpath.carts.line-item",
            "uri": "/carts/mobee/guz=/lineitems/gpq=",
            "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems/gpq="
          },
          "quantity": 1,
          "links": [
            {
              "rel": "item",
              "type": "elasticpath.items.item",
              "uri": "/items/mobee/m5yxi=",
              "href": "http://api.elasticpath.net/cortex/items/mobee/m5yxi="
            },
            {
              "rel": "cart",
              "type": "elasticpath.carts.cart",
              "uri": "/carts/mobee/guz=",
              "href": "http://api.elasticpath.net/cortex/carts/mobee/guz="
            },
            {
              "rel": "list",
              "type": "elasticpath.collections.links",
              "uri": "/carts/mobee/guz=/lineitems",
              "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems"
            },
            {
              "rel": "availability",
              "rev": "lineitem",
              "type": "elasticpath.availabilities.availability",
              "uri": "/availabilities/carts/mobee/guz=/lineitems/gpq=",
              "href": "http://api.elasticpath.net/cortex/availabilities/carts/mobee/guz=/lineitems/gpq="
            },
            {
              "rel": "price",
              "rev": "lineitem",
              "type": "elasticpath.prices.item-price",
              "uri": "/prices/carts/mobee/guz=/lineitems/gpq=",
              "href": "http://api.elasticpath.net/cortex/prices/carts/mobee/guz=/lineitems/gpq="
            }
          ]
        }
      ]
    }
  ],
  
  "_total": [
    {
      "self": {
        "type": "elasticpath.totals.total",
        "uri": "/totals/carts/mobee/guz=",
        "href": "http://api.elasticpath.net/cortex/totals/carts/mobee/guz="
      },
      "cost": [
        {
          "amount": 211,
          "currency": "CAD",
          "display": "$211.00"
        }
      ],
      "links": [
        {
          "rel": "cart",
          "rev": "total",
          "type": "elasticpath.carts.cart",
          "uri": "/carts/mobee/guz=",
          "href": "http://api.elasticpath.net/cortex/carts/mobee/guz="
        }
      ]
    }
  ]
}

Slimming Zoom responses

By using query parameters, you can get smaller Cortex zoom responses. The query parameters are :
  • standardlinks: Enable this parameter to get standard and slimmer links without uri and rev properties. This is applicable for plain JSON format. If passed while requesting a HAL response this parameters will have no effect.
  • zoom.noself: Enable this parameter to remove self in zoomed resources.
In Cortex Studio, you can set these parameters in the Setup section.
For the http://api.elasticpath.net/cortex/carts/mobee/default?zoom=total,lineitems:element:item:price&format=standardlinks,zoom.noself zoom request both the parameters are included, the response in Plain JSON format is as in the following example:
{
  "self": {
    "type": "carts.cart",
    "uri": "/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=?zoom=lineitems:element:item:price,total",
    "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=?zoom=lineitems:element:item:price,total"
  },
  "messages": [],
  "links": [
    {
      "rel": "lineitems",
      "type": "carts.line-items",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=/lineitems"
    },
    {
      "rel": "discount",
      "type": "discounts.discount-for-cart",
      "href": "http://api.elasticpath.net/cortex/discounts/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha="
    },
    {
      "rel": "order",
      "type": "orders.order",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/he2dimjygmzwcllemuydaljuhe2tkljymrtgellbhbrtazjtgi4dinleg4="
    },
    {
      "rel": "appliedpromotions",
      "type": "promotions.applied-promotions-for-cart",
      "href": "http://api.elasticpath.net/cortex/promotions/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=/applied"
    },
    {
      "rel": "total",
      "type": "totals.cart-total",
      "href": "http://api.elasticpath.net/cortex/totals/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha="
    }
  ],
  "_lineitems": [
    {
      "_element": [
        {
          "_item": [
            {
              "_price": [
                {
                  "messages": [],
                  "links": [
                    {
                      "rel": "item",
                      "type": "items.item",
                      "href": "http://api.elasticpath.net/cortex/items/mobee/qgqvhklbnruwk3s7onvxk="
                    }
                  ],
                  "list-price": [
                    {
                      "amount": 25.99,
                      "currency": "CAD",
                      "display": "$25.99"
                    }
                  ],
                  "purchase-price": [
                    {
                      "amount": 20,
                      "currency": "CAD",
                      "display": "$20.00"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "_item": [
            {
              "_price": [
                {
                  "messages": [],
                  "links": [
                    {
                      "rel": "item",
                      "type": "items.item",
                      "href": "http://api.elasticpath.net/cortex/items/mobee/qgqvhk3hojqxm2lupfpxg23v="
                    }
                  ],
                  "list-price": [
                    {
                      "amount": 50,
                      "currency": "CAD",
                      "display": "$50.00"
                    }
                  ],
                  "purchase-price": [
                    {
                      "amount": 50,
                      "currency": "CAD",
                      "display": "$50.00"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "_total": [
    {
      "messages": [],
      "links": [
        {
          "rel": "cart",
          "type": "carts.cart",
          "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha="
        }
      ],
      "cost": [
        {
          "amount": 70,
          "currency": "CAD",
          "display": "$70.00"
        }
      ]
    }
  ],
  "total-quantity": 2
}
For the http://api.elasticpath.net/cortex/carts/mobee/default?zoom=total,lineitems:element:item:price zoom query, the response in HAL format is as in the following example:
{
  "messages": [],
  "_links": {
    "self": {
      "name": "carts.cart",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/gbtdenbug43dmllegnstkljumnrtkllcmuytqljzgu4tondgga2wiobuha=?zoom=lineitems:element:item:price,total"
    },
    "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="
    }
  },
  "_embedded": {
    "total": {
      "messages": [],
      "_links": {},
      "cost": [
        {
          "amount": 70,
          "currency": "CAD",
          "display": "$70.00"
        }
      ]
    },
    "lineitems": {
      "messages": [],
      "_links": {},
      "_embedded": {
        "element": [
          {
            "messages": [],
            "_links": {},
            "_embedded": {
              "item": {
                "messages": [],
                "_links": {},
                "_embedded": {
                  "price": {
                    "messages": [],
                    "_links": {},
                    "list-price": [
                      {
                        "amount": 25.99,
                        "currency": "CAD",
                        "display": "$25.99"
                      }
                    ],
                    "purchase-price": [
                      {
                        "amount": 20,
                        "currency": "CAD",
                        "display": "$20.00"
                      }
                    ]
                  }
                }
              }
            }
          },
          {
            "messages": [],
            "_links": {},
            "_embedded": {
              "item": {
                "messages": [],
                "_links": {},
                "_embedded": {
                  "price": {
                    "messages": [],
                    "_links": {},
                    "list-price": [
                      {
                        "amount": 50,
                        "currency": "CAD",
                        "display": "$50.00"
                      }
                    ],
                    "purchase-price": [
                      {
                        "amount": 50,
                        "currency": "CAD",
                        "display": "$50.00"
                      }
                    ]
                  }
                }
              }
            }
          }
        ]
      }
    }
  },
  "total-quantity": 2
}