Query Parameters Supported by Cortex

Cortex supports setting these custom query parameters:

• zoom

  Retrieves linked data.

• followlocation

  Retrieves a resource referenced in the location header.

• format

  Provides options to specify how responses are returned.

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 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 rel to follow. For example:

• rel: ?zoom=rel1,rel2
• path: ?zoom=rel:rel:rel

Rels and paths are separated by the following characters:

• ,: 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

  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

  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. The 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 (Hypertext Application Language) 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 utility.

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
}

FollowLocation

The FollowLocation query parameter reduces the number of requests required when performing POST operations. FollowLocation instructs Cortex to retrieve the resource referenced in the Location header and return it in the response body which eliminates the need to make another call to retrieve the resource. FollowLocation can also be used with Zoom to further reduce the number of HTTP requests required.

When Cortex POST requests are made with the FollowLocation query parameter, Cortex actually processes operations against two resources:

• The origin resource: The resource that the Cortex POST was made against.
• The target resource: The resource that Cortex would normally redirect to, but which actually provides the response if the FollowLocation query parameter is included.

Some explanation is required to understand how FollowLocation handles failures. The returned HTTP status code is always determined by the origin resource. If the origin resource succeeds but the target resource operation fails, Cortex acts as if the FollowLocation request was not present and returns the origin resource response with a location header for the target resource. Cortex also returns a X-Ep-Follow-Location-Status header so the client can determine the result of the target resource operation. Additionally, if both resources succeed, the location header is not returned with the response, because we’re returning the target resource body with the response and we don't want the client to redirect to the location header value.

The behavior is summarized in the following table:

Origin Resource Response	Target Resource Response	HTTP status returned	HTTP X-Ep-Follow-Location-Status status returned	HTTP Location header returned	HTTP body returned
201	200	201	200	None	Target resource body
201	200	201	200	None	Target resource body
4XX or 5XX	N/A	4XX or 5XX	N/A	None	Origin resource body
201	4XX or 5XX	201	4XX or 5XX	Target resource location	Origin resource body
200	4XX or 5XX	200	4XX or 5XX	Target resource location	Origin resource body

Example: Add item to cart using FollowLocation

With the item resource’s addtocartform, you can add the item to a cart. To add the item to the cart and automatically retrieve the response, construct a POST request by:

• Using the form fields as the request body and the URL defined by the action link.
• Appending append the FollowLocation query parameter to the request.

POST /carts/mobee/default/lineitems/items/mobee/m5yxi=?FollowLocation
{
  "quantity" : 1
}

The returned response would be:

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

Example: Keyword Search using FollowLocation and Zoom

You can combine FollowLocation with Zoom to retrieve the resource referenced in the location header and any of that resource’s links. For example, with the search resource’s keywordsearchform, you can perform a keyword search for an item. To search for an item and automatically retrieve the search result’s links, construct a POST request by:

• Using the form fields as the request body and the URL defined by the action link.
• Appending the FollowLocation and Zoom query parameters to the request. The response includes the resource’s links as per normal Zoom rules.

POST /searches/mobee/keywords/items?FollowLocation&Zoom=element:definition
{
   "keywords" : "test"
}

The returned response would be:

{
  "self": {
    "type": "elasticpath.collections.paginated-links",
    "uri": "/searches/mobee/keywords/items/m43g==?zoom=element:definition",
    "href": "http://api.elasticpath.com/cortex/searches/mobee/keywords/items/m43g==?zoom=element:definition"
  },
  "pagination": {
    "current": 1,
    "page-size": 5,
    "pages": 1,
    "results": 3,
    "results-on-page": 3
  },
  "links": [
    {
      "rel": "element",
      "type": "elasticpath.items.item",
      "uri": "/items/mobee/m5y2=",
      "href": "http://api.elasticpath.com/cortex/items/mobee/m5y2="
    },
    {
      "rel": "element",
      "type": "elasticpath.items.item",
      "uri": "/items/mobee/m5yq=",
      "href": "http://api.elasticpath.com/cortex/items/mobee/m5yq="
    },
    {
      "rel": "element",
      "type": "elasticpath.items.item",
      "uri": "/items/mobee/m5ya=",
      "href": "http://api.elasticpath.com/cortex/items/mobee/m5ya="
    }
  ],
  "_element": [
    {
      "_definition": [
        {
          "self": {
            "type": "elasticpath.itemdefinitions.item-definition",
            "uri": "/itemdefinitions/mobee/m5y2=",
            "href": "http://api.elasticpath.com/cortex/itemdefinitions/mobee/m5y2="
          },
          "links": [
            {
              "rel": "item",
              "rev": "definition",
              "type": "elasticpath.items.item",
              "uri": "/items/mobee/m5y2=",
              "href": "http://api.elasticpath.com/cortex/items/mobee/m5y2="
            }
          ],
          "display-name": "Gravity"
        }
      ]
    },
    {
      "_definition": [
        {
          "self": {
            "type": "elasticpath.itemdefinitions.item-definition",
            "uri": "/itemdefinitions/mobee/m5yq=",
            "href": "http://api.elasticpath.com/cortex/itemdefinitions/mobee/m5yq="
          },
          "links": [
            {
              "rel": "item",
              "rev": "definition",
              "type": "elasticpath.items.item",
              "uri": "/items/mobee/m5yq=",
              "href": "http://api.elasticpath.com/cortex/items/mobee/m5yq="
            }
          ],
          "display-name": "Transformers Female"
        }
      ]
    },
    {
      "_definition": [
        {
          "self": {
            "type": "elasticpath.itemdefinitions.item-definition",
            "uri": "/itemdefinitions/mobee/m5ya=",
            "href": "http://api.elasticpath.com/cortex/itemdefinitions/mobee/m5ya="
          },
          "links": [
            {
              "rel": "item",
              "rev": "definition",
              "type": "elasticpath.items.item",
              "uri": "/items/mobee/m5ya=",
              "href": "http://api.elasticpath.com/cortex/items/mobee/m5ya="
            }
          ],
          "display-name": "Transformers Over 50"
        }
      ]
    }
  ]
}

Format

Cortex requests can include a format= query parameter that supports following option values:

• format=standardlinks

  Returns standard but slimmer links without uri and rev. Use this option to get smaller zoom responses.

• format=nolinks

  Omits all links from the response, except action links on forms. An action link is a link that accepts POST requests, such as addtodefaultcartaction. This option will also attempt to avoid conditional link evaluations for links that are not part of the zoom, which can improve response times in some circumstances. In general, we recommend using this format option for all production queries when discoverability is not needed.

• format=zoom.noself

  Omits self in zoomed resources.

• format=zoom.nodatalinks

  Omits data links in a zoomed resource. Use this option to return only the entity and the action links in zoomed resources. An action link is a link that accepts POST requests, such as addtodefaultcartaction.

  note

  The zoom.nodatalinks format is deprecated; use nolinks instead.

You can also combine the options in a single parameter with commas separating the option values, as in this example: format=standardlinks,nolinks,zoom.noself.