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.

https://api.wps-inc.com/products?include=items

Instead of retrieving an Item, making note of the product_id 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.

Using the same idea as the previous example but reversing the parent/child relationship, we can retrieve Items with their associated Product included.

https://api.wps-inc.com/items?include=product

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 (,).

https://api.wps-inc.com/products?include=features,images,items,tags

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.

https://api.wps-inc.com/products?include=items.images

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.

https://api.wps-inc.com/products?include=items.images.tags

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.

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:

https://api.wps-inc.com/products/207976?include=taxonomyterms

Get a collection of Items and include the Images associated with each of them.

https://api.wps-inc.com/items?include=images

Get a collection of Attributekeys and include the Attributevalues associated with each of them.

https://api.wps-inc.com/attributekeys?include=attributevalues

Get a collection of Attributevalues and include the one parent Attributekey associated to each of them.

https://api.wps-inc.com/attributevalues?include=attributekey