SmugMug API
Tutorial
API Concepts
Advanced
- Optimizing response sizes
- Expanding related data
- Configuring expansions
- Rate Limits
- Method and Content Overrides
- Performance Metrics
- Multi-get
- Options requests
Live API Browser
Reference
Expanding related data
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.