Expansions in the REST API
To limit the number of calls to the API, and the size of the responses, the Confluence REST API supports the expansion of certain elements. If your GET returns a list of results and you don't choose to expand anything, the response is terse, displaying only a basic representation of the resource. It will, however, include a list of the expandable items for the resource.
If you GET a specific piece of content – like a page by page ID (for example, where
12345 is the page ID – we expand some properties by default. For a specific page, we'll expand the space, history, and version information, but you can explicitly request expansion of different properties in your call.
On this page:
In this example, we'll send a GET to return a list of pages in the space with the space key, 'TEST':
Notice only id, status, title and type are expanded, but the _expandable block contains the properties that can be expanded.
Note that in the above example, even though there's only one piece of content returned, nothing is expanded by default because we didn't request a specific piece of content. We do though, get a list of expandable items.
Expand one or more items
As shown in the above example, you can use the expand parameter to explicitly expand any or all of the following items relating to the returned content item(s): history, body, container, ancestors, children, descendants, space, version, and metadata. Rather than creating multiple calls to return the information you need, you can make one call and only expand the items you need for your purpose.
If you need to expand more than one item, you can add them as a comma-separated list in the expand parameter. For example, if you need the
version information for the resource(s):
Notice that version and history are expanded because we specified expand=version,history as a query parameter in the request.
The above response provides an expanded view of the page history and version information. You should also notice that the expanded items can also contain nested items that can be further expanded. The 'history' element also contains: nextVersion, previousVersion, and lastUpdated, which can all be expanded in the response.
Expand nested items
As well as using a comma-separated list for expanding multiple elements, you can use dot-separated notation to expand nested elements.
For example, if you only need the history expanded, but you want to expand
Notice that the history object now includes the expanded lastUpdated object.
Modify expanded elements
Another example would be to expand the body of returned content in Confluence storage format (XHTML). If you GET the body in storage format, you can then PUT changes to that information to update the content. We'll also expand the version in this call, as we'll need to increment the version number when we PUT our changes.
You can then PUT your changes as follows:
Remember that Confluence pages and blog posts are versioned, so you'll need to add the version number in your call.