goconfluence

package module
v0.0.0-...-c9c8540 Latest Latest
Warning

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

Go to latest
Published: Jan 29, 2024 License: MIT Imports: 13 Imported by: 0

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) 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) 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) 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) 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 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 {
	Result []Version `json:"results"`
}

ContentVersionResult contains the version results

type Editor

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

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

Metadata specifies metadata properties

type Properties

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

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

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

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