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

Aug 3, 2024 • 7 minute read

Introduction

Hey there, fellow developer! Ready to dive into the world of Confluence API integration using Go? You're in for a treat. We'll be using the awesome confluence-go-api package to make our lives easier. Let's get cracking!

Prerequisites

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

Go installed on your machine
A Confluence account with an API token
Some basic Go knowledge and familiarity with RESTful APIs

Got all that? Great! Let's move on.

Setting up the project

First things first, let's create a new Go module:

mkdir confluence-integration
cd confluence-integration
go mod init confluence-integration

Now, let's install the confluence-go-api package:

go get github.com/virtomize/confluence-go-api

Initializing the Confluence client

Time to get our hands dirty! Let's import the necessary packages and create a new Confluence client:

package main

import (
    "fmt"
    "github.com/virtomize/confluence-go-api"
)

func main() {
    api, err := goconfluence.NewAPI("https://your-domain.atlassian.net", "[email protected]", "your-api-token")
    if err != nil {
        panic(err)
    }
    
    fmt.Println("Connected to Confluence!")
}

Basic operations

Now that we're connected, let's perform some basic operations:

Fetching a page

content, err := api.GetContent("pageID", goconfluence.ContentQuery{})
if err != nil {
    panic(err)
}
fmt.Printf("Page title: %s\n", content.Title)

Creating a new page

newPage := &goconfluence.Content{
    Type:  "page",
    Title: "My New Page",
    Space: &goconfluence.Space{Key: "SPACEKEY"},
    Body:  &goconfluence.Body{Storage: &goconfluence.Storage{Value: "<p>Hello, Confluence!</p>", Representation: "storage"}},
}

created, err := api.CreateContent(newPage)
if err != nil {
    panic(err)
}
fmt.Printf("Created page with ID: %s\n", created.ID)

Updating an existing page

content.Body.Storage.Value = "<p>Updated content!</p>"
content.Version.Number++

updated, err := api.UpdateContent(content)
if err != nil {
    panic(err)
}
fmt.Printf("Updated page version: %d\n", updated.Version.Number)

Deleting a page

err = api.DeleteContent(content.ID)
if err != nil {
    panic(err)
}
fmt.Println("Page deleted successfully!")

Advanced operations

Ready for some more advanced stuff? Let's go!

Working with attachments

attachments, err := api.GetAttachments("pageID")
if err != nil {
    panic(err)
}
for _, attachment := range attachments.Results {
    fmt.Printf("Attachment: %s\n", attachment.Title)
}

Managing page permissions

restrictions := &goconfluence.ContentRestrictions{
    Read: &goconfluence.ContentRestriction{
        Restrictions: &goconfluence.Restrictions{
            User: []goconfluence.User{{Name: "username"}},
        },
    },
}

err = api.UpdateContentRestrictions(content.ID, restrictions)
if err != nil {
    panic(err)
}
fmt.Println("Page restrictions updated!")

Searching for content

results, err := api.Search("label=mylabel", goconfluence.SearchQuery{})
if err != nil {
    panic(err)
}
for _, result := range results.Results {
    fmt.Printf("Found: %s\n", result.Title)
}

Error handling and best practices

When working with the Confluence API, always be mindful of rate limits. The confluence-go-api package handles retries for you, but it's good to be aware of it.

For error handling, wrap your API calls in try-catch blocks and handle specific error types when possible. For example:

_, err := api.GetContent("nonexistentID", goconfluence.ContentQuery{})
if err != nil {
    if err == goconfluence.ErrNoContent {
        fmt.Println("Content not found!")
    } else {
        fmt.Printf("An error occurred: %v\n", err)
    }
}

Testing the integration

Don't forget to write tests! Here's a quick example:

func TestGetContent(t *testing.T) {
    api, _ := goconfluence.NewAPI("https://your-domain.atlassian.net", "[email protected]", "your-api-token")
    
    content, err := api.GetContent("knownPageID", goconfluence.ContentQuery{})
    
    assert.NoError(t, err)
    assert.NotNil(t, content)
    assert.Equal(t, "Expected Title", content.Title)
}

Conclusion

And there you have it! You've just built a Confluence API integration in Go. Pretty cool, right? We've covered the basics and even dipped our toes into some advanced stuff. There's plenty more to explore, so don't be afraid to dive deeper into the confluence-go-api documentation and experiment with different API calls.

Remember, the key to mastering any API integration is practice and curiosity. So keep coding, keep exploring, and most importantly, have fun with it!

Resources

Happy coding, and may your Confluence pages always be in sync!