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:
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.