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.

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

Zoom can be added as a query parameter to any request. Commas and colons seperate 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.
  • The max-age of the response is the lowest max-age value of all zoomed links. In other words, if a linked resource cannot be cached (max-age = 0) then the entire zoomed resource cannot be cached.

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
If the zoom request has the correct syntax the response will return successfully even if the rel or path does not exist. The ensures that if links change overtime existing zoom requests will not break. 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 will be returned 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. This is the Internet's URL length restriction.
  • 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": "/commerce-legacy/carts/mobee/guz=",  
    "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=",
    "max-age": 0
  },
  "total-quantity" : 3,
  "links": [
    {
      "rel": "lineitems",
      "rev": "cart",
      "type": "elasticpath.collections.links",
      "uri": "/commerce-legacy/carts/mobee/guz=/lineitems",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems"
    },
    {
      "rel": "order",
      "rev": "cart",
      "type": "elasticpath.orders.order",
      "uri": "/commerce-legacy/orders/mobee/mu3=",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3="
    },
    {
      "rel": "total",
      "rev": "cart",
      "type": "elasticpath.totals.total",
      "uri": "/commerce-legacy/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": "/commerce-legacy/carts/mobee/guz=?zoom=lineitems,total",
    "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=?zoom=lineitems,total",
    "max-age": 0
  },
  "total-quantity": 3,
  "links": [
    {
      "rel": "lineitems",
      "rev": "cart",
      "type": "elasticpath.collections.links",
      "uri": "/commerce-legacy/carts/mobee/guz=/lineitems",
      "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems"
    },
    {
      "rel": "order",
      "rev": "cart",
      "type": "elasticpath.orders.order",
      "uri": "/commerce-legacy/orders/mobee/mu3=",
      "href": "http://api.elasticpath.net/cortex/orders/mobee/mu3="
    },
    {
      "rel": "total",
      "rev": "cart",
      "type": "elasticpath.totals.total",
      "uri": "/commerce-legacy/totals/carts/mobee/guz=",
      "href": "http://api.elasticpath.net/cortex/totals/carts/mobee/guz="

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