- Data Depot
- Version 4
- API Token
- Order Processing
API News and Updates
Subscribe to stay alert on the API.
One of the most practical and convenient functions of the API, includes are essentially a way to nest one service within another service based on the relationship they have with each another.
This important feature makes your requests much more efficient and greatly reduces the need to make multiple requests to gather all the pieces of data you desire. For those with a database background, think of includes as a "join". With includes you are essentially joining another related database table to the primary entity and nesting it under each item in the response.
Probably the most commonly used example of this functionality would be to request Products with their associated Items included.
Instead of retrieving an Item, making note of the
on the Item, and making another request to get the parent Product;
we can simply get the Product and include all of it's associated Items.
Works with any valid relationshipIncludes are not limited to parent/child relationships; you can also get child/parent relationships. This allows you to incorporate any parent service within a child service provided they have appropriate relationship to one another.
Using the same idea as the previous example but reversing the parent/child relationship, we can retrieve Items with their associated Product included.
Pay special attention to singularity versus plurality of this request. A Product can have many Items, but an Item only belongs to one Product.
You can also combine multiple includes to produce even more powerful queries. Just separate each include with a comma (,).
You can take includes a step further and retrieve an includes associations as well. Just separate each association by a dot (.). A request like this will include all the Items associated to a Product, but it will also include the Images associated to those Items as well.
It doesn't stop at one level either. You can essentially include an infinite amount of relationship data on an include! You can go as deep as the relationships go. All you have to do is separate each association by a dot (.).
This request will return all the Items associated to a Product, but it will also include the Images associated to those Items and the Tags associated to those Images.
Keep in mind that this is just an example to help illustrate the usage of Nested includes. In reality, deep relationships like that are few and far between. Currently we don't have many (if any) Tags associated to Images but hopefully this example will help you grasp the concept.
Collection or Entities
Includes work the same on collection or entity requests. If we were to request one particular Product and include all it's Taxonomyterms, the request would look something like this:
Get a collection of Items and include the Images associated with each of them.
Get a collection of Attributekeys and include the Attributevalues associated with each of them.
Get a collection of Attributevalues and include the one parent Attributekey associated to each of them.