goconfluence

package module
v1.4.1 Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2022 License: MIT Imports: 20 Imported by: 13

README

confluence-go-api

Remark: This is a fork from virtomize - not yet merged

Main features:

  • Using a properties file to make automation easier
  • The Extender for Confluence plugin, used for user, group and permissions

Donate GoDoc Go Report Card License Build Status 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: https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html. 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.

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

func StripHTML 

func StripHTML(buf []byte, bodyOnly, stripImg bool) string

StripHTML removes the specified information from the HTML and sets it as a string

Types

type API 

type API struct {
	Client *http.Client

	Debug bool
	// 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) AddPage 

func (a *API) AddPage(title, spaceKey, filepath string, bodyOnly, stripImgs bool, ancestor string) error

AddPage adds a new page to the space with the given title, TODO what if page already exists?

func (*API) AddSpaceCategory 

func (a *API) AddSpaceCategory(spaceKey string, category string) (*AddCategoryResponseType, error)

AddSpaceCategory /rest/extender/1.0/category/addSpaceCategory/space/{SPACE_KEY}/category/{CATEGORY_NAME}

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

func (a *API) DoRequest(endpoint string, method string, responseContainer interface{}) error

func (*API) GetAllGroupsWithAnyPermission 

func (a *API) GetAllGroupsWithAnyPermission(spacekey string, options *PaginationOptions) (*GetAllGroupsWithAnyPermissionType, error)

func (*API) GetAllSpaces 

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

GetAllSpaces queries content using a query parameters

func (*API) GetAllUsersWithAnyPermission 

func (a *API) GetAllUsersWithAnyPermission(spacekey string, options *PaginationOptions) (*GetAllUsersWithAnyPermissionType, error)

func (*API) GetAttachments 

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

GetAttachments returns a list of attachments belonging to id

func (*API) GetBlueprintTemplates 

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 

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

GetContentTemplates querys for content templates

func (*API) GetContentVersion 

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

GetContentVersion gets all versions of this content

func (*API) GetGroupPermissionsForSpace 

func (a *API) GetGroupPermissionsForSpace(spacekey, group string) (*GetPermissionsForSpaceType, error)

func (*API) GetGroups 

func (a *API) GetGroups(options *GetGroupMembersOptions) (*GroupsType, error)

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

func (a *API) GetPageId(spacename string, pagename string) (*ContentSearch, error)

func (*API) GetPermissionTypes 

func (a *API) GetPermissionTypes() (*PermissionsTypes, error)

func (*API) GetUserPermissionsForSpace 

func (a *API) GetUserPermissionsForSpace(spacekey, user string) (*GetPermissionsForSpaceType, error)

func (*API) GetUsers 

func (a *API) GetUsers(group string, options *GetGroupMembersOptions) (*UsersType, error)

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

func (a *API) SendAddCategoryRequest(ep *url.URL, method string) (*AddCategoryResponseType, error)

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 

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

SendContentVersionRequest requests a version of a specific content

func (*API) SendGenericRequest 

func (a *API) SendGenericRequest(ep, method string) ([]byte, error)

SendGenericRequest sends a greneric request

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

func (a *API) UppdateAttachment(spacename string, pagename string, filename string) error

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 AddCategoryResponseType 

type AddCategoryResponseType struct {
	Status string `json:"status"`
}

type AllSpaces 

type AllSpaces struct {
	Links struct {
		Base    string `json:"base"`
		Context string `json:"context"`
		Self    string `json:"self"`
	} `json:"_links"`
	Limit   int64 `json:"limit"`
	Results []struct {
		Expandable struct {
			Description     string `json:"description"`
			Homepage        string `json:"homepage"`
			Icon            string `json:"icon"`
			Metadata        string `json:"metadata"`
			RetentionPolicy string `json:"retentionPolicy"`
		} `json:"_expandable"`
		Links struct {
			Self  string `json:"self"`
			Webui string `json:"webui"`
		} `json:"_links"`
		ID   int64  `json:"id"`
		Key  string `json:"key"`
		Name string `json:"name"`
		Type string `json:"type"`
	} `json:"results"`
	Size  int64 `json:"size"`
	Start int64 `json:"start"`
}

type AllSpaces2 

type AllSpaces2 struct {
	Links struct {
		Base    string `json:"base"`
		Context string `json:"context"`
		Self    string `json:"self"`
	} `json:"_links"`
	Limit   int64 `json:"limit"`
	Results []struct {
		Expandable struct {
			Description     string `json:"description"`
			Homepage        string `json:"homepage"`
			Icon            string `json:"icon"`
			Metadata        string `json:"metadata"`
			RetentionPolicy string `json:"retentionPolicy"`
		} `json:"_expandable"`
		Links struct {
			Self  string `json:"self"`
			Webui string `json:"webui"`
		} `json:"_links"`
		ID   int64  `json:"id"`
		Key  string `json:"key"`
		Name string `json:"name"`
		Type string `json:"type"`
	} `json:"results"`
	Size  int64 `json:"size"`
	Start int64 `json:"start"`
}

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
	Label            string
}

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 Body 

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

Body holds the storage information

type BodyExportView 

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"`
}

Content specifies content properties

type ContentAppearanceDraft 

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

ContentAppearanceDraft sets the appearance of the content in draft form

type ContentAppearancePublished 

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 

type ContentVersionResult struct {
	Links struct {
		Base    string `json:"base"`
		Context string `json:"context"`
		Self    string `json:"self"`
	} `json:"_links"`
	Limit   int64 `json:"limit"`
	Results []struct {
		Expandable struct {
			Content string `json:"content"`
		} `json:"_expandable"`
		Links struct {
			Self string `json:"self"`
		} `json:"_links"`
		By struct {
			DisplayName    string `json:"displayName"`
			ProfilePicture struct {
				Height    int64  `json:"height"`
				IsDefault bool   `json:"isDefault"`
				Path      string `json:"path"`
				Width     int64  `json:"width"`
			} `json:"profilePicture"`
			Type string `json:"type"`
		} `json:"by"`
		Hidden    bool   `json:"hidden"`
		Message   string `json:"message"`
		MinorEdit bool   `json:"minorEdit"`
		Number    int64  `json:"number"`
		When      string `json:"when"`
	} `json:"results"`
	Size  int64 `json:"size"`
	Start int64 `json:"start"`
}

type Editor 

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

Editor contains editor information

type GetAllGroupsWithAnyPermissionType 

type GetAllGroupsWithAnyPermissionType struct {
	Groups     []string `json:"groups"`
	MaxResults int64    `json:"maxResults"`
	StartAt    int64    `json:"startAt"`
	Total      int64    `json:"total"`
}

type GetAllUsersWithAnyPermissionType 

type GetAllUsersWithAnyPermissionType struct {
	MaxResults int64    `json:"maxResults"`
	StartAt    int64    `json:"startAt"`
	Total      int64    `json:"total"`
	Users      []string `json:"users"`
}

type GetGroupMembersOptions 

type GetGroupMembersOptions struct {
	MaxResults int `json:"maxResults"`
	StartAt    int `json:"startAt"`
}

type GetPermissionsForSpaceType 

type GetPermissionsForSpaceType struct {
	Key         string   `json:"key"`
	Name        string   `json:"name"`
	Permissions []string `json:"permissions"`
}

type GroupsType 

type GroupsType struct {
	Groups     []string `json:"groups"`
	MaxResults int64    `json:"maxResults"`
	StartAt    int64    `json:"startAt"`
	Status     string   `json:"status"`
	Total      int64    `json:"total"`
}

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"`
}

Links contains link information

type Metadata 

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

Metadata specifies metadata properties

type PaginationOptions 

type PaginationOptions struct {
	// StartAt: The starting index of the returned projects. Base index: 0.
	StartAt int `url:"startAt,omitempty"`
	// MaxResults: The maximum number of projects to return per page. Default: 50.
	MaxResults int `url:"maxResults,omitempty"`
}

type PermissionsTypes 

type PermissionsTypes []string

type Properties 

type Properties struct {
	Editor                     *Editor                     `json:"editor"`
	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"`
	ID        string    `json:"id,omitempty"`
	TotalSize int       `json:"totalSize,omitempty"`
}

Search results

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 

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 

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

TemplateQuery defines the query parameters

type TemplateSearch 

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 UsersType 

type UsersType struct {
	MaxResults int64  `json:"maxResults"`
	StartAt    int64  `json:"startAt"`
	Status     string `json:"status"`
	Total      int64  `json:"total"`
	Users      []struct {
		Business []struct {
			Department string `json:"department"`
			Location   string `json:"location"`
			Position   string `json:"position"`
		} `json:"business"`
		CreatedDate                   int64       `json:"createdDate"`
		CreatedDateString             string      `json:"createdDateString"`
		Email                         string      `json:"email"`
		FullName                      string      `json:"fullName"`
		HasAccessToUseConfluence      bool        `json:"hasAccessToUseConfluence"`
		Key                           string      `json:"key"`
		LastFailedLoginDate           interface{} `json:"lastFailedLoginDate"`
		LastFailedLoginDateString     interface{} `json:"lastFailedLoginDateString"`
		LastSuccessfulLoginDate       int64       `json:"lastSuccessfulLoginDate"`
		LastSuccessfulLoginDateString string      `json:"lastSuccessfulLoginDateString"`
		Name                          string      `json:"name"`
		Personal                      []struct {
			Im      string `json:"im"`
			Phone   string `json:"phone"`
			Website string `json:"website"`
		} `json:"personal"`
		UpdatedDate       int64  `json:"updatedDate"`
		UpdatedDateString string `json:"updatedDateString"`
	} `json:"users"`
}

type Version 

type Version struct {
	Number    int    `json:"number"`
	MinorEdit bool   `json:"minorEdit"`
	Message   string `json:"message,omitempty"`
	By        *User  `json:"by,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
content
labels
search
space
user
main module

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.