goconfluence

package module
v1.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 22, 2025 License: MIT Imports: 14 Imported by: 70

README

confluence-go-api

Donate GoDoc Go Report Card License Built with Mage

is a Confluence REST API client implementation written in GOLANG.

Supported Features

  • get, update, delete content
  • get, update, delete content templates and blueprints
  • get comments, attachments, children of content objects, history, watchers
  • get, add ,delete labels
  • get user information
  • search using CQL

If you miss some feature implementation, feel free to open an issue or send pull requests. I will take look as soon as possible.

Donation

If this project helps you, feel free to give us a cup of coffee :).

paypal

Installation

If you already installed GO on your system and configured it properly than its simply:

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

If not follow these instructions

Usage

Simple example
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)
}
Using a Personal Access Token

To generate a confluence personal access token (PAT) see this article: using personal access tokens. Only set the token in the NewAPI function

  api, err := goconfluence.NewAPI("https://<your-domain>.atlassian.net/wiki/rest/api", "", "<personal-access-token>")
Advanced examples

see examples for some more usage examples

Code Documentation

You find the full code documentation here.

The Confluence API documentation can be found here.

Contribution

Thank you for participating to this project. Please see our Contribution Guidlines for more information.

Pre-Commit

This repo uses pre-commit hooks. Please install pre-commit and do pre-commit install

Conventional Commits

Format commit messaged according to Conventional Commits standard.

Semantic Versioning

Whenever you need to version something make use of Semantic Versioning.

Documentation

Overview

Package goconfluence implementing atlassian's Confluence API

Simple example: 

//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)

supported features:

  • get user information
  • create, update, delete content
  • get comments, attachments, history, watchers and children of content objects
  • get, add, delete labels
  • search using CQL

see https://github.com/virtomize/confluence-go-api/tree/master/examples for more information and usage examples

Index

Constants

This section is empty.

Variables

View Source 
var DebugFlag = false

DebugFlag is the global debugging variable

Functions

func Debug 

func Debug(msg interface{})

Debug outputs debug messages

func SetDebug 

func SetDebug(state bool)

SetDebug enables debug output

Types

type API 

type API struct {
	Client *http.Client
	// contains filtered or unexported fields
}

API is the main api data structure

func NewAPI 

func NewAPI(location string, username string, token string) (*API, error)

NewAPI implements API constructor

func NewAPIWithClient 

func NewAPIWithClient(location string, client *http.Client) (*API, error)

NewAPIWithClient creates a new API instance using an existing HTTP client. Useful when using oauth or other authentication methods.

func (*API) AddLabels 

func (a *API) AddLabels(id string, labels *[]Label) (*Labels, error)

AddLabels returns adds labels

func (*API) AnonymousUser 

func (a *API) AnonymousUser() (*User, error)

AnonymousUser return user information for anonymous user

func (*API) Auth 

func (a *API) Auth(req *http.Request)

Auth implements basic auth

func (*API) CreateContent 

func (a *API) CreateContent(c *Content) (*Content, error)

CreateContent creates content

func (*API) CurrentUser 

func (a *API) CurrentUser() (*User, error)

CurrentUser return current user information

func (*API) DelContent 

func (a *API) DelContent(id string) (*Content, error)

DelContent deletes content by id

func (*API) DeleteLabel 

func (a *API) DeleteLabel(id string, name string) (*Labels, error)

DeleteLabel removes a label by name from content identified by id

func (*API) GetAllSpaces 

func (a *API) GetAllSpaces(query AllSpacesQuery) (*AllSpaces, error)

GetAllSpaces queries content using a query parameters

func (*API) GetAttachmentById added in v1.5.0 

func (a *API) GetAttachmentById(id string) (*Attachment, error)

Get info on specific attachment by id

func (*API) GetAttachments 

func (a *API) GetAttachments(id string) (*Search, error)

GetAttachments returns a list of attachments belonging to id

func (*API) GetBlueprintTemplates added in v1.2.7 

func (a *API) GetBlueprintTemplates(query TemplateQuery) (*TemplateSearch, error)

GetBlueprintTemplates querys for content blueprints defined by TemplateQuery parameters

func (*API) GetChildPages 

func (a *API) GetChildPages(id string) (*Search, error)

GetChildPages returns a content list of child page objects

func (*API) GetComments 

func (a *API) GetComments(id string) (*Search, error)

GetComments returns a list of comments belonging to id

func (*API) GetContent 

func (a *API) GetContent(query ContentQuery) (*ContentSearch, error)

GetContent querys content using a query parameters

func (*API) GetContentByID 

func (a *API) GetContentByID(id string, query ContentQuery) (*Content, error)

GetContentByID querys content by id

func (*API) GetContentTemplates added in v1.2.7 

func (a *API) GetContentTemplates(query TemplateQuery) (*TemplateSearch, error)

GetContentTemplates querys for content templates

func (*API) GetContentVersion added in v1.2.7 

func (a *API) GetContentVersion(id string) (*ContentVersionResult, error)

GetContentVersion gets all versions of this content

func (*API) GetHistory 

func (a *API) GetHistory(id string) (*History, error)

GetHistory returns history information

func (*API) GetLabels 

func (a *API) GetLabels(id string) (*Labels, error)

GetLabels returns a list of labels attachted to a content object

func (*API) GetWatchers 

func (a *API) GetWatchers(id string) (*Watchers, error)

GetWatchers returns a list of watchers

func (*API) Request 

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

Request implements the basic Request function

func (*API) Search 

func (a *API) Search(query SearchQuery) (*Search, error)

Search querys confluence using CQL

func (*API) SearchWithNext added in v1.5.1 

func (a *API) SearchWithNext(query SearchQuery, next string) (*Search, error)

Search querys confluence using CQL, with the ability to pass in the Next header Empty Next header will run search like normal

func (*API) SendAllSpacesRequest 

func (a *API) SendAllSpacesRequest(ep *url.URL, method string) (*AllSpaces, error)

SendAllSpacesRequest sends a request for all spaces

func (*API) SendContentAttachmentRequest 

func (a *API) SendContentAttachmentRequest(ep *url.URL, attachmentName string, attachment io.Reader, params map[string]string) (*Search, error)

SendContentAttachmentRequest sends a multipart/form-data attachment create/update request to a content

func (*API) SendContentRequest 

func (a *API) SendContentRequest(ep *url.URL, method string, c *Content) (*Content, error)

SendContentRequest sends content related requests this function is used for getting, updating and deleting content

func (*API) SendContentVersionRequest added in v1.2.7 

func (a *API) SendContentVersionRequest(ep *url.URL, method string) (*ContentVersionResult, error)

SendContentVersionRequest requests a version of a specific content

func (*API) SendHistoryRequest 

func (a *API) SendHistoryRequest(ep *url.URL, method string) (*History, error)

SendHistoryRequest requests history

func (*API) SendLabelRequest 

func (a *API) SendLabelRequest(ep *url.URL, method string, labels *[]Label) (*Labels, error)

SendLabelRequest requests history

func (*API) SendSearchRequest 

func (a *API) SendSearchRequest(ep *url.URL, method string) (*Search, error)

SendSearchRequest sends search related requests

func (*API) SendUserRequest 

func (a *API) SendUserRequest(ep *url.URL, method string) (*User, error)

SendUserRequest sends user related requests

func (*API) SendWatcherRequest 

func (a *API) SendWatcherRequest(ep *url.URL, method string) (*Watchers, error)

SendWatcherRequest requests watchers

func (*API) UpdateAttachment 

func (a *API) UpdateAttachment(id string, attachmentName string, attachmentID string, attachment io.Reader) (*Search, error)

UpdateAttachment update the attachment with an attachmentID on a page with an id to a new version

func (*API) UpdateContent 

func (a *API) UpdateContent(c *Content) (*Content, error)

UpdateContent updates content

func (*API) UploadAttachment 

func (a *API) UploadAttachment(id string, attachmentName string, attachment io.Reader) (*Search, error)

UploadAttachment uploaded the given reader as an attachment to the page with the given id. The existing attachment won't be updated with a new version number

func (*API) User 

func (a *API) User(query string) (*User, error)

User returns user data for defined query query can be accountID or username

func (*API) VerifyTLS 

func (a *API) VerifyTLS(set bool)

VerifyTLS to enable disable certificate checks

type AllSpaces 

type AllSpaces struct {
	Results []Space `json:"results"`
	Start   int     `json:"start,omitempty"`
	Limit   int     `json:"limit,omitempty"`
	Size    int     `json:"size,omitempty"`
}

AllSpaces results

type AllSpacesQuery 

type AllSpacesQuery struct {
	Expand           []string
	Favourite        bool   // Filter the results to the favourite spaces of the user specified by favouriteUserKey
	FavouriteUserKey string // The userKey of the user, whose favourite spaces are used to filter the results when using the favourite parameter. Leave blank for the current user
	Limit            int    // page limit
	SpaceKey         string
	Start            int    // page start
	Status           string // current, archived
	Type             string // global, personal
}

AllSpacesQuery defines the query parameters Query parameter values https://developer.atlassian.com/cloud/confluence/rest/#api-space-get

type Ancestor 

type Ancestor struct {
	ID string `json:"id"`
}

Ancestor defines ancestors to create sub pages

type Attachment added in v1.5.0 

type Attachment struct {
	MediaTypeDescription string      `json:"mediaTypeDescription"`
	WebuiLink            string      `json:"webuiLink"`
	DownloadLink         string      `json:"downloadLink"`
	CreatedAt            interface{} `json:"createdAt"`
	ID                   string      `json:"id"`
	Comment              string      `json:"comment"`
	Version              struct {
		Number    int       `json:"number"`
		Message   string    `json:"message"`
		MinorEdit bool      `json:"minorEdit"`
		AuthorID  string    `json:"authorId"`
		CreatedAt time.Time `json:"createdAt"`
	} `json:"version"`
	Title     string `json:"title"`
	FileSize  int    `json:"fileSize"`
	Status    string `json:"status"`
	PageID    string `json:"pageId"`
	FileID    string `json:"fileId"`
	MediaType string `json:"mediaType"`
	Links     struct {
		Download string `json:"download"`
		Webui    string `json:"webui"`
	} `json:"_links"`
}

type Body 

type Body struct {
	Storage Storage  `json:"storage"`
	View    *Storage `json:"view,omitempty"`
}

Body holds the storage information

type BodyExportView added in v1.2.8 

type BodyExportView struct {
	ExportView *Storage `json:"export_view"`
	View       *Storage `json:"view,omitempty"`
}

BodyExportView holds the export_view information

type Content 

type Content struct {
	ID        string     `json:"id,omitempty"`
	Type      string     `json:"type"`
	Status    string     `json:"status,omitempty"`
	Title     string     `json:"title"`
	Ancestors []Ancestor `json:"ancestors,omitempty"`
	Body      Body       `json:"body"`
	Version   *Version   `json:"version,omitempty"`
	Space     *Space     `json:"space"`
	History   *History   `json:"history,omitempty"`
	Links     *Links     `json:"_links,omitempty"`
	Metadata  *Metadata  `json:"metadata,omitempty"`
}

Content specifies content properties

type ContentAppearanceDraft added in v1.4.0 

type ContentAppearanceDraft struct {
	Value string `json:"value"`
}

ContentAppearanceDraft sets the appearance of the content in draft form

type ContentAppearancePublished added in v1.4.0 

type ContentAppearancePublished struct {
	Value string `json:"value"`
}

ContentAppearancePublished sets the appearance of the content in published form

type ContentQuery 

type ContentQuery struct {
	Expand     []string
	Limit      int    // page limit
	OrderBy    string // fieldpath asc/desc e.g: "history.createdDate desc"
	PostingDay string // required for blogpost type Format: yyyy-mm-dd
	SpaceKey   string
	Start      int    // page start
	Status     string // current, trashed, draft, any
	Title      string // required for page
	Trigger    string // viewed
	Type       string // page, blogpost
	Version    int    //version number when not lastest

}

ContentQuery defines the query parameters used for content related searching Query parameter values https://developer.atlassian.com/cloud/confluence/rest/#api-content-get

type ContentSearch 

type ContentSearch struct {
	Results []Content `json:"results"`
	Start   int       `json:"start,omitempty"`
	Limit   int       `json:"limit,omitempty"`
	Size    int       `json:"size,omitempty"`
}

ContentSearch results

type ContentVersionResult added in v1.2.7 

type ContentVersionResult struct {
	Result []Version `json:"results"`
}

ContentVersionResult contains the version results

type Editor added in v1.4.0 

type Editor struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

Editor contains editor information

type History 

type History struct {
	LastUpdated LastUpdated `json:"lastUpdated"`
	Latest      bool        `json:"latest"`
	CreatedBy   User        `json:"createdBy"`
	CreatedDate string      `json:"createdDate"`
}

History contains object history information

type Label 

type Label struct {
	Prefix string `json:"prefix"`
	Name   string `json:"name"`
	ID     string `json:"id,omitempty"`
	Label  string `json:"label,omitempty"`
}

Label contains label information

type Labels 

type Labels struct {
	Labels []Label `json:"results"`
	Start  int     `json:"start,omitempty"`
	Limit  int     `json:"limit,omitempty"`
	Size   int     `json:"size,omitempty"`
}

Labels is the label containter type

type LastUpdated 

type LastUpdated struct {
	By           User   `json:"by"`
	When         string `json:"when"`
	FriendlyWhen string `json:"friendlyWhen"`
	Message      string `json:"message"`
	Number       int    `json:"number"`
	MinorEdit    bool   `json:"minorEdit"`
	SyncRev      string `json:"syncRev"`
	ConfRev      string `json:"confRev"`
}

LastUpdated contains information about the last update 

type Links struct {
	Base     string `json:"base"`
	TinyUI   string `json:"tinyui"`
	WebUI    string `json:"webui"`
	Download string `json:"download"`
}

Links contains link information

type Metadata added in v1.4.0 

type Metadata struct {
	Properties *Properties `json:"properties"`
}

Metadata specifies metadata properties

type Properties added in v1.4.0 

type Properties struct {
	Editor                     *Editor                     `json:"editor,omitempty"`
	ContentAppearanceDraft     *ContentAppearanceDraft     `json:"content-appearance-draft"`
	ContentAppearancePublished *ContentAppearancePublished `json:"content-appearance-published"`
}

Properties defines properties of the editor

type Results 

type Results struct {
	ID      string  `json:"id,omitempty"`
	Type    string  `json:"type,omitempty"`
	Status  string  `json:"status,omitempty"`
	Content Content `json:"content"`
	Excerpt string  `json:"excerpt,omitempty"`
	Title   string  `json:"title,omitempty"`
	URL     string  `json:"url,omitempty"`
}

Results array 

type Search struct {
	Results   []Results   `json:"results"`
	Start     int         `json:"start,omitempty"`
	Limit     int         `json:"limit,omitempty"`
	Size      int         `json:"size,omitempty"`
	TotalSize int         `json:"totalSize,omitempty"`
	Links     SearchLinks `json:"_links,omitempty"`
}

Search results 

type SearchLinks struct {
	Base    string `json:"base,omitempty"`
	Context string `json:"content,omitempty"`
	Next    string `json:"next,omitempty"`
	Self    string `json:"self,omitempty"`
}

Parsing out the _links section to allow paging etc.

type SearchQuery 

type SearchQuery struct {
	CQL                   string
	CQLContext            string
	IncludeArchivedSpaces bool
	Limit                 int
	Start                 int
	Expand                []string
}

SearchQuery defines query parameters used for searchng Query parameter values https://developer.atlassian.com/cloud/confluence/rest/#api-search-get

type Space 

type Space struct {
	ID     int    `json:"id,omitempty"`
	Key    string `json:"key,omitempty"`
	Name   string `json:"name,omitempty"`
	Type   string `json:"type,omitempty"`
	Status string `json:"status,omitempty"`
}

Space holds the Space information of a Content Page

type Storage 

type Storage struct {
	Value          string `json:"value"`
	Representation string `json:"representation"`
}

Storage defines the storage information

type Template added in v1.2.7 

type Template struct {
	ID          string `json:"templateId,omitempty"`
	Name        string `json:"name,omitempty"`
	Type        string `json:"templateType,omitempty"`
	Description string `json:"description"`
	Body        Body   `json:"body"`
	Space       Space  `json:"space"`
}

Template contains blueprint data

type TemplateQuery added in v1.2.7 

type TemplateQuery struct {
	SpaceKey string
	Start    int // page start
	Limit    int // page limit
	Expand   []string
}

TemplateQuery defines the query parameters

type TemplateSearch added in v1.2.7 

type TemplateSearch struct {
	Results []Template `json:"results"`
	Start   int        `json:"start,omitempty"`
	Limit   int        `json:"limit,omitempty"`
	Size    int        `json:"size,omitempty"`
}

TemplateSearch contains blueprint search results

type User 

type User struct {
	Type        string `json:"type"`
	Username    string `json:"username"`
	UserKey     string `json:"userKey"`
	AccountID   string `json:"accountId"`
	DisplayName string `json:"displayName"`
}

User defines user informations

type Version 

type Version struct {
	Number    int    `json:"number"`
	MinorEdit bool   `json:"minorEdit"`
	Message   string `json:"message,omitempty"`
	By        *User  `json:"by,omitempty"`
	When      string `json:"when,omitempty"`
}

Version defines the content version number the version number is used for updating content

type Watcher 

type Watcher struct {
	Type      string `json:"type"`
	Watcher   User   `json:"watcher"`
	ContentID int    `json:"contentId"`
}

Watcher contains information about watching users of a page

type Watchers 

type Watchers struct {
	Watchers []Watcher `json:"results"`
	Start    int       `json:"start,omitempty"`
	Limit    int       `json:"limit,omitempty"`
	Size     int       `json:"size,omitempty"`
}

Watchers is a list of Watcher

Source Files

View all Source files

Directories

Path Synopsis
examples
attributes command
content command
labels command
search command
space command
user command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.