We are excited to announce the release of our first public Confluence GraphQL APIs, now in beta.
We’re big fans of GraphQL because it allows you to clearly see the relationships between different entities and objects. You can also write queries that provide exactly the data you need. Compared to REST APIs, GraphQL often reduces the number of requests and makes it easier to process the response because you won’t get back any data you didn’t ask for.
Developer experience was central to creating these APIs – starting with our own. The Confluence GraphQL APIs were originally developed for use by our internal engineering teams. However, we knew early on that we would want to make these APIs publicly available, for two reasons. First, it brings our internal teams closer to using the same tools available to our external ecosystem developers. Second, we wanted external developers to be able to benefit from these APIs just as we did.
We set out to design an API that would be enjoyable, intuitive, and effective to use. To this end, we started with entirely fresh queries and mutations, working to follow industry best practices.
Our philosophy is that mutations should do one thing and do it well, an approach recommended by many GraphQL resources. Because of this, you might observe the mutations and some queries are quite specific. This has the advantage of better type safety, since the arguments can then be typed for exactly that mutation. No more guessing which of the 5+ arguments is actually required or not!
We’ve taken a minimalist approach so far – this is intentional. We want to make sure we are moving forward carefully and gathering feedback as we go. We plan to add more functionality as we learn more about how these APIs are being used. Our goal is to get feedback and work in a collaborative manner with the developer community.
Before we go on:
Please note that these APIs are in beta, and you must provide the following header when making your query:
{"X-ExperimentalApi" : "confluence-agg-beta"}
We are excited to share these APIs early so that we can continue to iterate and develop them in partnership with you. As a result, we may change these APIs at any time as we learn more about how to make them better. Some of these queries are also experimental and are subject to change as we iterate.
Try it out
The GraphQL Explorer allows you to build and test API requests right in your browser. We’ve included a few sample requests in this blog post that you can use to start getting a feel for the API. You can also check out the documentation to see everything you can do with the Confluence GraphQL API.
The Confluence GraphQL API has been added to the Atlassian GraphQL API, which accesses data across all Atlassian products. This means we have one communication standard across all our public GraphQL APIs, giving you one powerful place to query different products at once.
Heads up!
In Atlassian’s GraphQL Gateway, all entities should be queried using their ARIs. An ARI is an Atlassian Resource Identifier. Effectively it’s the type of resource + the id of the resource + some routing information. We need this in the GraphQL world because we have one single entry point, the AGG, and thus need to have routing information to know which tenant to actually go to. In the cases where the query wouldn’t have an ARI, you will instead need to provide your Cloud ID + whatever other arguments are needed.
Getting your cloud ID
query getCloudIdForTenant {
tenantContexts(hostNames:["your-domain.atlassian.net"]) {
cloudId
}
}This will then return a cloud ID:
"cloudId": "a436116f-02ce-4520-8fbb-7301462a1674"
You can now use the cloud ID in your ARIs. If you query using all GraphQL ARIs then you will be given ARIs back that you can use for more calls. If you want to directly query something from just its ID you will have to manually build the ARI as our REST APIs do not currently return them. Some common ARIs you may need are:
ARI: ari:cloud:confluence:{cloudId}:blogpost/{blogpostId}
ARI: ari:cloud:confluence:{cloudId}:page/{pageId}
ARI: ari:cloud:confluence:{cloudId}:space/{spaceId}
ARI: ari:cloud:confluence:{cloudId}:comment/{commentId}A few key points before diving into the examples
Alongside industry standards, we follow an Atlassian standard which is compatible with the very popular Relay pagination standard.
See the GraphQL Cursor Connections Specification here.
We also have standards that we follow for mutations. All mutations in the AGG follow this same format. You can see this payload by looking at the schema explorer.
Operation names
All queries and mutations must have operation names. We ask you follow the following format:
<your_app_name>_<area eg:Admin>_<operationDescription>
eg: myConfluenceApp_user_createSpaceForNewDataNote for Forge apps:
Forge apps should make their requests to https://api.atlassian.com/graphql. The reason the URLs are different is they use different methods of auth, Session vs OAuth, and each URL serves a different purpose.
Beta header
As this is in Beta, you will currently have to start by adding a Beta header.
{"X-ExperimentalApi" : "confluence-agg-beta"}If you are using GraphQL this can be found in the lower left corner as “Request Headers”.
Lets go through an example workflow
In this example, we’ll create a new Confluence space, add a page in draft mode, edit the page, and then publish it.
To begin, visit the GraphQL found on your instance. This can be located at yourTenant/gateway/api/graphql.
For example, https://developer.atlassian.com/platform/atlassian-graphql-api/graphql/explorer/
- Get your cloud ID
query myConfluenceApp_user_getCloudId {
tenantContexts(hostNames:"myHost.url.com") {
cloudId
}
}The CloudId we get back is: a6a01d21-1cc3-4f29-9565-f2bb8cd969f5.
2. Create a space
mutation myConfluenceApp_user_createSpace {
confluence {
confluenceCreateSpace(cloudId: "a6a01d21-1cc3-4f29-9565-f2bb8cd969f5", input: {
key: "testSpaceKey"
name: "My Test Space"
}) {
success
confluenceSpace {
id
}
}
}
}
The only thing we for sure need from this response is the Space ID, because we’ll need this in the next step. In general when creating any type of resource you will want to get the ID so that you can easily reference it again, since the ID will be an ARI.
The ID of the new Space is: ari:cloud:confluence:a6a01d21-1cc3-4f29-9565-f2bb8cd969f5:space/4522109845
3. Create a page as a draft
mutation myConfluenceApp_user_createPage {
confluence {
confluenceCreatePage(input: {
spaceId: "ari:cloud:confluence:a6a01d21-1cc3-4f29-9565-f2bb8cd969f5:space/4522109845",
title: "i am a page title"
status: DRAFT
}) {
confluencePage {
id
}
}
}
}The ID of the new page is: ari:cloud:confluence:a6a01d21-1cc3-4f29-9565-f2bb8cd969f5:page/633859.
4. Edit the draft
mutation myConfluenceApp_user_updatePage {
confluence {
confluenceUpdateDraftPage(input: {
id: "ari:cloud:confluence:a6a01d21-1cc3-4f29-9565-f2bb8cd969f5:page/633859"
title: "My Updated Title"
}) {
success
}
}
}5. Publish the page
mutation myConfluenceApp_user_publishPage {
confluence {
confluencePublishPage(input: {
id: "ari:cloud:confluence:a6a01d21-1cc3-4f29-9565-f2bb8cd969f5:page/633859"
}) {
success
}
}
}Next steps
Jump in and try out the Confluence GraphQL API using the GraphQL explorer, where you can see all of the available queries, mutations, and types, and check out the docs for full details.
During the beta, we’re keen to get your feedback. Please join the discussion in the Developer Community by tagging your community questions with confluence-graphql 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 GraphQL API.