Confluence API Essential Guide

What type of API does Confluence provide?

REST API

Confluence has a REST API that is the primary and recommended API for developers to use. The REST API provides access to various Confluence resources and capabilities.

GraphQL API

Confluence also offers a GraphQL API, which was released in beta in March 2022. Key points about the GraphQL API include:

• It allows developers to query exactly the data they need, reducing the number of requests compared to REST APIs.
• It provides a clearer view of relationships between different entities and objects.
• It's part of the Atlassian GraphQL API, which accesses data across all Atlassian products.
• During the beta, developers need to include a special header: {"X-ExperimentalApi" : "confluence-agg-beta"}

JSON-RPC API (Deprecated)

Confluence previously had a JSON-RPC API, but it was deprecated since Confluence 5.5. Key points about this deprecated API:

• It exposed all existing Confluence SOAP services via the JSON-RPC 2.0 standard.
• It was implemented as a plugin bundled with Confluence 4.1 and later.
• It was compatible with Confluence 3.5 and later.

Best Practices

1. For new development, use the REST API or the GraphQL API (when it becomes generally available).
2. The REST API is more mature and widely supported.
3. Consider using the GraphQL API for complex queries that require data from multiple related entities, as it can be more efficient.
4. Avoid using the deprecated JSON-RPC API for new development.

In summary, while Confluence has had multiple API types in the past, the current recommended APIs are REST and GraphQL (in beta), with REST being the primary choice for most developers.

Does the Confluence API have webhooks?

Webhooks are available in Confluence Server and Data Center versions 7.7 and later. Webhooks allow you to notify an external application or service when certain events occur in Confluence. You can create webhooks using the REST API or through the Confluence UI.

Some of the events you can subscribe to include:

• page_created
• page_updated
• page_removed
• comment_created
• space_created
• user_deactivated

To create a webhook via the API, you make a POST request to /rest/api/webhooks with the webhook details in JSON format. The webhook configuration includes the name, events to subscribe to, URL to send notifications, whether it's active or not, and an optional secret for verification.

You can query existing webhooks using a GET request to /rest/api/webhooks.

For Confluence Cloud, webhooks can only be registered through the descriptor file of an add-on, not from the UI. There is an open feature request (CONFCLOUD-36613) to allow webhook administration through the UI for Confluence Cloud.

Rate Limits and other limitations

Here are the key points about API rate limits for the Confluence API:

General Rate Limiting Approach

• Confluence uses rate limiting to ensure services remain reliable and responsive for customers [2].

• Rate limiting targets only external REST API requests, not internal Confluence traffic [4].

• Confluence uses a token bucket algorithm for rate limiting [4]:

  • Users get tokens that are exchanged for requests (1 token = 1 request)
  • Tokens are replenished at a constant rate (e.g. 10 tokens every 1 minute)
  • There's a maximum token bucket size (e.g. 20 tokens)

Specific Limits

• For Confluence Cloud, the exact rate limits are not published as they evolve continuously [2].

• For Confluence Server/Data Center, administrators can configure custom rate limits [4]:

  • Options include allowing unlimited requests, blocking all requests, or setting specific limits
  • Limits are applied per node in a Data Center cluster, not cluster-wide

Handling Rate Limits

• When rate limited, requests will receive a 429 HTTP status code [1][4].

• Apps should implement backoff and retry logic to handle rate limits [2].

• Confluence provides context parameters to help minimize necessary API requests [2].

Exemptions and Allowlisting

• Administrators can add exemptions for specific users or applications [4].

• Consumer keys for external applications can be allowlisted to bypass rate limits [4].

• Specific URLs/resources can be allowlisted using system properties [4].

Best Practices

• Use multi-threading carefully, as high concurrency increases chances of hitting rate limits [2].

• Consider factors like request idempotency, contention, timeouts, etc. when implementing retry logic [2].

• For migrations, use the Migration-App header to access migration-specific rate limits [2].

• Monitor rate limited requests in Confluence logs for troubleshooting [4].

The exact rate limits are not published for Confluence Cloud, so you'll need to implement proper error handling and backoff logic. For Confluence Server/Data Center, work with administrators to configure appropriate limits and exemptions as needed.

Latest API Version

Based on the search results provided, here is the most up-to-date information about the Confluence API versions:

Current API Versions

The Confluence API currently has two main versions:

1. Confluence Cloud REST API v2 (latest version)
2. Confluence Cloud REST API v1 (being deprecated)

Deprecation of v1 API

The Confluence Cloud REST API v1 is in the process of being deprecated. However, the exact timeline for full deprecation is not finalized. Key points to consider:

• Atlassian has postponed the removal of service for all v1 endpoints until at least June 2024.
• They have committed to not removing access to any v1 endpoint until there is at least 6 months of feature parity in the v2 API.
• As of May 2024, there was no fixed date announced for the complete deprecation of v1 endpoints.

Migration to v2 API

Atlassian is encouraging developers to migrate from v1 to v2 API:

• The @forge/ui-confluence library version 13 and higher uses Confluence v2 REST APIs.
• Versions 12 and lower of this library use deprecated Confluence v1 REST APIs and will stop functioning after the deprecation date.

Best Practices

1. Start migrating your applications to use the v2 API if you haven't already.
2. Keep an eye on the Atlassian Developer Community and official changelogs for updates on the deprecation timeline.
3. When using the @forge/ui-confluence library, update to version 13 or higher and adjust your app's manifest to use the new required permission scopes.

Summary

While the Confluence Cloud REST API v2 is the most recent version and should be used for new development, the v1 API is still accessible. Atlassian is working on achieving feature parity between v1 and v2 before fully deprecating v1. Developers should plan to migrate to v2, but there is currently no immediate deadline for this migration.

How to get a Confluence developer account and API Keys?

To get a developer account for Confluence and create an API integration, here are the key steps:

1. Sign up for an Atlassian account

If you don't already have one, you'll need to create an Atlassian account at https://id.atlassian.com/signup.

2. Access the Atlassian Developer Portal

Go to https://developer.atlassian.com/ and log in with your Atlassian account.

3. Explore the Confluence Cloud API documentation

On the developer portal, navigate to the Confluence Cloud section to access:

• REST API documentation
• Tutorials and guides
• Getting started information
• Changelog

4. Set up your development environment

Before starting API development:

• Read the developer guide to understand high-level concepts
• Consider using Forge, Atlassian's cloud development platform, for building hosted apps

5. Authentication

For personal use and scripts, you can use:

• Basic authentication with username and password
• Personal access token (for Confluence Data Center 7.9+)

6. Start developing

Use standard HTTP methods (GET, PUT, POST, DELETE) to interact with Confluence resources via the REST API.

What can you do with the Confluence API?

Based on the Confluence REST API documentation, here are the main data models you can interact with using the Confluence API, along with key points about what is possible for each:

Content

• Create, read, update, and delete content (pages, blog posts, etc.)
• Manage content properties
• Handle content versions and history
• Manage content restrictions and permissions
• Work with child content and descendants
• Add/remove labels
• Manage attachments
• Handle content watchers

Spaces

• Create, read, update, and delete spaces
• Manage space properties
• Add/remove space labels
• Handle space permissions and restrictions
• Manage space watchers

Users

• Get user information
• Manage user groups
• Handle user watches (content/spaces being watched)

Search

• Perform advanced searches using Confluence Query Language (CQL)
• Search across content, spaces, users, etc.

Other Models

• Groups - Create, read, update, delete groups
• Attachments - Upload, download, update attachments
• Labels - Add/remove labels from content and spaces
• Properties - Manage custom properties on content and spaces
• Restrictions - Set view/edit restrictions on content
• Versions - Work with content version history
• Watchers - Manage watchers for content and spaces

Key Points

• Most models support CRUD operations (Create, Read, Update, Delete)
• Expansions allow fetching additional related data in a single call
• Pagination is supported to limit result sets
• Authentication is required, with permissions checks applied
• The API uses standard HTTP methods and returns JSON responses
• Advanced searching is possible using CQL queries

The Confluence API provides comprehensive access to manage and interact with most aspects of the Confluence data model programmatically.