Using Confluence API

Introduction

The Confluence API provides a way to interact programmatically with the Confluence platform. It allows you to create, read, update, and delete content, manage users, and perform various other actions. This tutorial will guide you through the process of using the Confluence API effectively.

Prerequisites

Before you start using the Confluence API, ensure you have the following:

• A Confluence account with API access rights.
• A tool to make HTTP requests (e.g., Postman, cURL, or any programming language with HTTP support).
• Basic knowledge of RESTful APIs and JSON format.

Authentication

To access the Confluence API, you need to authenticate your requests. Confluence supports basic authentication and OAuth. For simplicity, we'll use basic authentication in this tutorial.

To authenticate, include your username and an API token in the request headers. You can generate an API token from your Confluence account settings.

curl -u username:api_token -X GET "https://your-domain.atlassian.net/wiki/rest/api/content"

Making Your First API Call

Now that you are authenticated, let's make our first API call. We will fetch the list of all pages in a space.

curl -u username:api_token -X GET "https://your-domain.atlassian.net/wiki/rest/api/space/{spaceKey}/content"

Replace {spaceKey} with the key of your space (e.g., "DOC"). This command will return a JSON response containing the pages.

Understanding the Response

The API will return a JSON object containing an array of page objects. Each page object includes properties such as id, title, and type.

{
    "results": [
        {
            "id": "123456",
            "title": "Sample Page",
            "type": "page",
            "space": {
                "key": "DOC"
            }
        }
    ],
    "size": 1,
    "_links": {
        "self": "https://your-domain.atlassian.net/wiki/rest/api/content?spaceKey=DOC"
    }
}

Creating a New Page

You can also create new pages using the API. To do this, you'll need to send a POST request with the page details in JSON format.

curl -u username:api_token -X POST -H "Content-Type: application/json" --data '{
    "type": "page",
    "title": "New Page",
    "space": {
        "key": "DOC"
    },
    "body": {
        "storage": {
            "value": "
This is a new page.
",
            "representation": "storage"
        }
    }
}' "https://your-domain.atlassian.net/wiki/rest/api/content"

This command creates a new page in the specified space with the given title and content.

Updating a Page

If you need to update an existing page, you'll send a PUT request with the updated content. You'll need to specify the page ID in the URL.

curl -u username:api_token -X PUT -H "Content-Type: application/json" --data '{
    "version": {
        "number": 2
    },
    "title": "Updated Page Title",
    "type": "page",
    "body": {
        "storage": {
            "value": "
This page has been updated.
",
            "representation": "storage"
        }
    }
}' "https://your-domain.atlassian.net/wiki/rest/api/content/{pageId}"

Replace {pageId} with the ID of the page you want to update. Make sure to increment the version number with each update.

Deleting a Page

To delete a page, you will send a DELETE request to the API. You must provide the page ID in the URL.

curl -u username:api_token -X DELETE "https://your-domain.atlassian.net/wiki/rest/api/content/{pageId}"

This command will delete the specified page from Confluence.

Conclusion

The Confluence API provides powerful capabilities for managing content programmatically. By following the steps outlined in this tutorial, you can start integrating with Confluence and automating your content management tasks. Always refer to the official Confluence REST API documentation for more detailed information and advanced usage.