With expansions, you can combine many related API requests into one. In some situations, this can improve the performance of your application.

To use expansions, just make a request, and name the related URIs you want to retrieve at the same time in the _expand query argument:

In this example, we've requested the user cmac and expanded the UserProfile URI. This means that we are getting the responses to both /api/v2/user/cmac and /api/v2/user/cmac!profile. You can find the latter URI by looking at Response.User.Uris.UserProfile.Uri.

In the combined response, the response to the root URI (/api/v2/user/cmac) will appear in the normal place. Expanded responses appear in the Expansions object, which is indexed by the expanded URI:

Expanding from a multiple-object response

If you expand from a response which returns multiple objects, you'll get an expanded response for each object, assuming all the objects have the kind of URI you are expanding. For example, to expand all the highlight images of cmac's top-level folders, you could make this request:

The response is pretty big, so we're not going to include it here. But you can either look at this gist or the live response. Notice that the HighlightImage URI of each folder appears separately in the Expansions object.

More ways to expand

You aren't limited to a single expansion!

To expand multiple URIs, just separate the names with commas:

/api/v2/folder/user/cmac?_expand=FolderAlbums,Folders

To expand from an expansion, add on the second layer with a period:

/api/v2/folder/user/cmac?_expand=Folders.HighlightImage

You can even use commas and dots together:

/api/v2/folder/user/cmac?_expand=FolderAlbums.HighlightImage,Folders.HighlightImage

Inline Expansions

If you'd rather, you can request that expansions be returned inline, nested inside Response.Uris. Just add _expandmethod=inline to the query.

This feature should be used with caution: if you end up expanding the same URI multiple times, using inline expansions will cause that response content to be duplicated, making the response larger. For example, if you were to expand UserAlbums.Folder, and there were ten albums with the same parent folder, you would get ten copies of that parent folder response, nested inside the albums' Uris.Folder sections.

Here is an example you can try:

/api/v2/folder/user/cmac?expand=FolderAlbums,Folders&expandmethod=inline

Expansions and query arguments

To add configuration options to your expansions, such as filters or query parameters, you will need to use the alternate expansion syntax.