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

Directories

Path Synopsis
examples
main module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL