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
- 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:
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:
- 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
- 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.
- 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": "/commerce-legacy/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": "/commerce-legacy/carts/mobee/guz=/lineitems",
- "href": "http://api.elasticpath.net/cortex/carts/mobee/guz=/lineitems"
- },
...
Read more
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"
- },
- "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"
- },
...
Read more
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="
- },
- "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"
- },
...
Read more
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"
- },
- "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="
- },
- {
...
Read more
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"
- },
- "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"
- },
...
Read more