Last October, we released the first REST API V2 endpoints for Confluence Cloud, which enabled developers to fetch pages and blogposts. We’ve continued to expand the surface area of the V2 API, and we are now happy to announce the release of V2 endpoints related to the following data types:
- attachments
- blogposts
- comments
- custom content
- labels
- pages
- spaces
- space properties
- versions
These endpoints support Connect scopes and granular OAuth 2.0 scopes.
The REST API V2 offers two main improvements over previous versions: endpoint specialization and lower request latency. Endpoints that have specific, restricted scope behave predictably, are easier to optimize, and are compatible with our commitment to granular OAuth 2.0 scopes.
The end of content
Confluence has numerous types of publishable data – pages, blogposts, comments, and attachments – each of which differ substantially. We consider each type to be distinct, in the same way that pages and spaces are distinct. To reflect this distinction, the version 2 API offers separate endpoints for each data type. It does not use the term Content, and it does not offer endpoints for fetching or manipulating Content as a broad concept.
This separation of endpoints allows REST API V2 to be fully compatible with granular OAuth 2.0 scopes.
The end of expansions
In the REST API V2, response payloads do not contain nested data types that are served by other endpoints; instead, any references to different data types are identifiers that can be passed to separate API calls to fetch the corresponding data. Because of this, REST API V2 does not support expansions or the expand query parameter.
Expansions are contrary to the concept of specialized endpoints, since they enable fetching arbitrary data types from a single endpoint. Endpoints without expansions enable lower request latency, since database calls are much more predictable and easier to optimize.
API consumers who require expansions should consider using the Confluence GraphQL API.
For example, a client makes the following call:
GET https://mysite.atlassian.net/wiki/api/v2/pages/12345?body-format=storageThe returned response may have the following payload:
{
"version": {
"createdAt": "2020-08-06T18:58:08.473Z",
"minorEdit": false,
"message": "",
"number": 1
},
"id": 360450,
"title": "My Space",
"status": "current",
"body": {
"storage": {
"value": ...
"representation": "STORAGE"
}
},
"spaceId": 360449
}Note that the payload contains a spaceId field, rather than a space field. The client can pass the spaceId value to a different endpoint to fetch the corresponding space.
Cursor pagination and lower latency
The REST API V2 uses cursor-based pagination instead of the offset-based pagination present in REST API V1. Cursor-based pagination provides two main benefits:
- Cursor-paginated requests have substantially better latency than offset-paginated requests, especially when comparing high-offset requests with the equivalent cursor-paginated requests.
- Adding or deleting data during cursor-based pagination does not result in missing data. In offset-based pagination, on the other hand, adding or removing an item causes the indices of all following items to increase or decrease by one; if this occurs while a client is paginating, an item will be included again or missing from the client's next page.
A cursor-paginated response includes a Link header, the value of which contains a full URL that serves the next page of results.
For example, a client makes the following call:
GET https://mysite.atlassian.net/wiki/api/v2/pages?limit=1The returned response will have the following header and value:
Link: <https://lpan.atlassian.net/wiki/api/v2/pages?limit=1&cursor=CURSOR>; rel="next"Get started
Documentation for the REST API V2 is available here.
Clients can make requests to the API in the same manner they would for REST API V1, but a key difference is that the base path for V2 is /wiki/api/v2.
What's next?
We strongly encourage developers to start using the new and improved version of the Confluence REST API in their apps. With its combination of specialization and speed, it vastly outperforms the previous version of the API, and we believe both building and using apps will be better than ever before.
During these early stages, we’re keen to get your feedback. Please join the discussion in the Developer Community by tagging your community questions with rest-api-v2 to surface them to our team. Let us know what use cases you’re building, as well as what feature requests and fixes you’d like to see. We’re excited to work closely with you to shape the future of the Confluence REST API V2.