I spent a bit of time today looking into the Confluence Cloud API. There are some projects that I've wanted to look into developing.
One of them is trying to solve the problem of there being tons of Confluence docs all over an organization, many of which may be out of date, unused, or of unknown veracity.
One idea is that you can assign pages to people and give them reminders in Confluence to update the page after a certain amount of time. Another idea is that you could crawl the Confluence links across the organization and generate a report or filterable visualization that helps you find delete-able content.
Confluence gives you a few ways that you can integrate with them, ranging from using their own frameworks (sellable on the Confluence app store, hosted by Confluence) to making a standalone 3P application (not sellable, self-hosted). This page gives a good overview of the different integration points. I started out by following the steps in making a new Connect App which set up my Confluence space for me and allowed me to get an API key for subsequent steps.
For anyone interested in starting by checking out the data they expose as quickly as possible, I recommend using the Swagger / OpenAPI Spec that Confluence has sneakily posted on their REST API docs page (click the ellipses next to "Rate this page").
Once you have the URL, you can import the collection and the API into Postman.
Some things to take note of:
- You might want to fork the Collection before you make changes just so you don't have to continually delete and re-import the Open API spec.
- Most URLs will need to have the params disabled before they will work for you because the default param values are often invalid
- If you want to just get up and running ASAP, you might want to just use Basic Auth (as described below) and make sure to switch the auth method for each request you are using.
Since the default Postman collection API auth method is set to OAuth 2, and I wanted to start pulling data as quickly as possible, instead of messing about with OAuth 2, I just set all the sub-folders in the Postman collection to inherit from the parent, and then at the parent level in Postman, set up "Basic Auth" in Postman with my Confluence email/username as the username, and a generated API key as the password (also see: this link)
Just in case you hit bumps along the way, assuming you have:
- generated an API key
- have a Confluence Server Cloud domain
you should be able to run a request like this and get a 2XX back, with of course your email, real token, and real domain replacing the below.
curl -D- -u [email protected]:api_token_here -X GET -H "Content-Type: application/json" https://mydomain.atlassian.net/wiki/rest/api/spaceI wanted to focus on the possibilities for the Confluence link crawler, so I was trying to find out which endpoints could give me the most easily consumable access to URLs / links.
I found by trial and error that this endpoint, Get content by ID:
`/api/content/:id?expand=body.dynamic`will return a JSON blob of structured content that represents the content blocks on your page, including rich-formatted links, which allows you to avoid nasty string parsing, at the cost of ripping through deeply nested JSON.
I only discovered this JSON option after seeing this link and this other link which covers expansions in the API generally.
The next time I look at Confluence, I'm looking forward to looking more at some of the cool things they provide like Atlassian.design which gives guidance on designing apps for their system, as well as the Atlassian Marketplace Developer docs. But I'm not looking forward to refreshing on all the different auth models they provide (Oauth, token, etc) and different permission granularities (space-level, group level, etc.) which will be more important as I look into developing a real application.