Step by Step Guide to Building a Confluence API Integration in JS

Introduction

Hey there, fellow developer! Ready to supercharge your Confluence experience with some JavaScript magic? You're in the right place. We're going to dive into building a Confluence API integration using the awesome confluence.js package. This nifty tool will let you interact with Confluence programmatically, opening up a world of automation possibilities.

Prerequisites

Before we jump in, make sure you've got:

• Node.js and npm installed (you're a dev, so I'm sure you do!)
• A Confluence account with an API token (if you don't have one, go grab it from your account settings)
• Some JavaScript chops and familiarity with async/await (nothing too fancy, I promise)

Setting Up the Project

Let's get our project off the ground:

1. Fire up your terminal and create a new directory:

   mkdir confluence-api-integration
   cd confluence-api-integration
   

2. Initialize your npm project:

   npm init -y
   

3. Install the star of our show, the confluence.js package:

   npm install confluence.js
   

Configuring the Confluence Client

Now, let's set up our Confluence client:

const Confluence = require('confluence.js');

const confluence = new Confluence({
    baseUrl: 'https://your-domain.atlassian.net/wiki',
    username: '[email protected]',
    password: 'your-api-token'
});

Replace the placeholders with your actual Confluence domain, email, and API token. Easy peasy!

Basic Operations

Fetching a Page

Let's grab a page and see what we've got:

async function getPage(pageId) {
    try {
        const page = await confluence.content.getContent({ id: pageId });
        console.log('Page title:', page.title);
    } catch (error) {
        console.error('Oops! Something went wrong:', error);
    }
}

Creating a New Page

Time to unleash your creativity:

async function createPage(spaceKey, title, content) {
    try {
        const newPage = await confluence.content.createContent({
            space: { key: spaceKey },
            title: title,
            type: 'page',
            body: { storage: { value: content, representation: 'storage' } }
        });
        console.log('New page created with ID:', newPage.id);
    } catch (error) {
        console.error('Page creation failed:', error);
    }
}

Updating an Existing Page

Let's give that page a makeover:

async function updatePage(pageId, newContent) {
    try {
        const page = await confluence.content.getContent({ id: pageId });
        const updatedPage = await confluence.content.updateContent({
            id: pageId,
            type: 'page',
            title: page.title,
            version: { number: page.version.number + 1 },
            body: { storage: { value: newContent, representation: 'storage' } }
        });
        console.log('Page updated successfully');
    } catch (error) {
        console.error('Update failed:', error);
    }
}

Deleting a Page

Sometimes, we need to say goodbye:

async function deletePage(pageId) {
    try {
        await confluence.content.deleteContent({ id: pageId });
        console.log('Page deleted successfully');
    } catch (error) {
        console.error('Deletion failed:', error);
    }
}

Advanced Operations

Working with Attachments

Spice up your pages with some attachments:

async function addAttachment(pageId, filePath) {
    try {
        const attachment = await confluence.content.createAttachment({
            id: pageId,
            file: filePath
        });
        console.log('Attachment added:', attachment.title);
    } catch (error) {
        console.error('Attachment upload failed:', error);
    }
}

Managing Page Permissions

Keep your content secure:

async function setPagePermissions(pageId, username, permission) {
    try {
        await confluence.content.restrictContent({
            id: pageId,
            operation: 'update',
            restrictions: {
                user: [{ type: 'known', username: username }],
                operation: permission
            }
        });
        console.log('Permissions updated successfully');
    } catch (error) {
        console.error('Failed to update permissions:', error);
    }
}

Searching for Content

Find that needle in the haystack:

async function searchContent(query) {
    try {
        const results = await confluence.content.searchContent({ cql: query });
        console.log('Search results:', results.results);
    } catch (error) {
        console.error('Search failed:', error);
    }
}

Error Handling and Best Practices

Always wrap your API calls in try-catch blocks to handle errors gracefully. And remember, Confluence has rate limits, so be kind to the API. Consider implementing retries with exponential backoff for important operations.

Example: Building a Simple Confluence Content Manager

Let's put it all together:

async function contentManager() {
    const spaceKey = 'YOUR_SPACE_KEY';
    const pageTitle = 'My Awesome Page';
    const content = '<p>Hello, Confluence!</p>';

    // Create a new page
    const newPage = await createPage(spaceKey, pageTitle, content);

    // Update the page
    await updatePage(newPage.id, '<p>Updated content!</p>');

    // Add an attachment
    await addAttachment(newPage.id, './my-image.png');

    // Set permissions
    await setPagePermissions(newPage.id, '[email protected]', 'read');

    // Search for the page
    await searchContent(`title ~ "${pageTitle}"`);

    // Delete the page (careful with this one!)
    // await deletePage(newPage.id);
}

contentManager().catch(console.error);

Conclusion

And there you have it! You're now equipped to build some seriously cool Confluence integrations. Remember, this is just scratching the surface. The confluence.js package has a ton more features to explore.

Keep experimenting, and don't be afraid to dive into the official Confluence API documentation for even more ideas. Happy coding, and may your Confluence pages always be informative and your integrations smooth!