confluence-go-api

The confluence-go-api client supports the following operations:

• Content Management: Get, update, and delete content.
• Templates & Blueprints: Get, update, and delete content templates and blueprints.
• Metadata & Relationships: Get comments, attachments, children of content objects, history, and watchers.
• Labels: Get, add, and delete labels.
• Users: Get user information.
• Search: Search using CQL (Confluence Query Language).

To install the confluence-go-api package, use the standard Go get command. Ensure that Go is already installed and configured on your system.

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

The following core types define the structure of Confluence data in this library:

• Content: The primary object representing a page or blog post. Includes Title, Body, Version, Space, History, and Metadata.
• Body: Contains the Storage (the actual content value and its representation, e.g., storage) and an optional View.
• Version: Represents a specific iteration of content, used for updates. Contains Number, Message, and By (user).
• Space: Represents the Confluence space the content belongs to, containing Key, Name, and Type.
• Metadata: Contains Properties such as Editor information or ContentAppearance (draft vs published).

Use the user.go example pattern to interact with user data in Confluence. This allows you to:

• Get the currentUser
• Get the AnonymousUser
• Retrieve a specific user by their name or accountid

// Refer to examples/user.go for implementation details
// Supports: get currentUser, AnonymousUser or user by name/accountid

Use the labels.go example pattern to manage the labels associated with content. You can:

• Get existing labels
• Add new labels
• Delete labels

// Refer to examples/labels.go for implementation details
// Supports: get, add, delete labels

Use the attributes.go example pattern to fetch metadata and associated entities for a specific piece of content. This includes:

• Comments
• Attachments
• Child pages
• History (versioning)
• Watchers

// Refer to examples/attributes.go for implementation details
// Supports: get comments, attachments, child pages, history and watchers

Use the content.go example pattern to perform basic CRUD operations on Confluence content. This includes retrieving existing content, creating new content entries, and updating existing ones.

// Refer to examples/content.go for implementation details
// Supports: get, create and update content

Use the search.go example pattern to perform searches within Confluence using Confluence Query Language (CQL).

// Refer to examples/search.go for implementation details
// Supports: searching example using CQL

Once the API instance is initialized, you can retrieve information about the currently authenticated user using the CurrentUser() method.

package main

import (
  "fmt"
  "log"

  "github.com/virtomize/confluence-go-api"
)

func main() {
  // initialize a new api instance
  api, err := goconfluence.NewAPI("https://<your-domain>.atlassian.net/wiki/rest/api", "<username>", "<api-token>")
  if err != nil {
    log.Fatal(err)
  }

  // get current user information
  currentUser, err := api.CurrentUser()
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%+v\n", currentUser)
}

Use goconfluence.NewAPI to create a new API instance. You can authenticate using either a username/API token combination or a Personal Access Token (PAT).

Using Username and API Token: Pass the Confluence REST API base URL, your username, and your Atlassian API token.

Using a Personal Access Token (PAT): Pass the Confluence REST API base URL, an empty string for the username, and your PAT as the third argument.

// Using Username and API Token
api, err := goconfluence.NewAPI("https://<your-domain>.atlassian.net/wiki/rest/api", "<username>", "<api-token>")

// Using a Personal Access Token (PAT)
api, err := goconfluence.NewAPI("https://<your-domain>.atlassian.net/wiki/rest/api", "", "<personal-access-token>")

The API allows navigating the hierarchy and metadata of a content item:

• GetChildPages(id string): Returns a Search object containing a list of Results (which include Content summaries) for all child pages of the given ID. It automatically handles pagination to fetch all children.
• GetComments(id string): Returns a Search object containing comments belonging to the content.
• GetAttachments(id string): Returns a Search object containing attachments belonging to the content.

The Request method is the core engine for all API calls. It takes a standard *http.Request, automatically handles authentication (if credentials are provided in the API instance), and sets the Accept: application/json, */* header.

It handles common HTTP status codes by returning the response body as []byte for success codes (200 OK, 201 Created, 206 Partial Content) or nil for empty responses (204 No Content, 203 Reset Content).

It returns errors for:

• 401 Unauthorized: "authentication failed"
• 503 Service Unavailable: "service is not available: <status>"
• 500 Internal Server Error: "internal server error: <status>"
• 409 Conflict: "conflict: <status>"

func (a *API) Request(req *http.Request) ([]byte, error)