Add-on to extend projectdoc with an API to access on the web.

Parent: projectdoc Extensions
Categories: / projectdoc / Extension
Confluence Version: 9.0.x
Version: 13.0.1
projectdoc Toolbox: 7.2.0

Contents

REST Resources
REST Services
Accessing the API
Logging
Version Tags
Subordinate Topics
Resources

projectdoc documents provide properties via the Document Properties Marker Macro and (optionally) Document Properties Supplier Macro.

These properties may define and document real configuration data or metadata information. Therefore there are use cases where teams want to access these properties from other information systems.

This extension provides a REST web API to query space properties and document properties.

Representations are rendered in JSON and XML. Queries, supported for projectdoc documents, may also return representations in CSV. Properties for space and document instances are also available in the Java Properties format.

REST Resources

The extension provides one resource to request representations for spaces and one for documents.

This is the list of REST resources provided by the projectdoc Web-API Extension:

Document Resource: Provides access to projectdoc documents via a web API.
Document Services Resource: Provides services for projectdoc documents via a web API.
I18N Resource: Services to access localized information via the I18N services.
Space Resource: Provides access to projectdoc space properties.

REST Services

The extension provides the following services on document and space resources.

Path	HTTP Method	Short Description
`rest/projectdoc/1/document`	GET	Supports queries on projectdoc documents.
`rest/projectdoc/1/document`	PATCH	Adds, removes, and applies changes to properties and sections of a projectdoc document.
`rest/projectdoc/1/document`	POST	Creates a new projectdoc document based on a document representation.
`rest/projectdoc/1/document/{id}`	DELETE	Deletes the referenced projectdoc document.
`rest/projectdoc/1/document/{id}`	GET	Provides access to a projectdoc document.
`rest/projectdoc/1/document/{id}`	PATCH	Updates projectdoc documents.
`rest/projectdoc/1/document/{id}/property/{name}`	DELETE	Deletes a document property.
`rest/projectdoc/1/document/{id}/property/{name}`	GET	Provides access to a projectdoc document property.
`rest/projectdoc/1/document/{id}/property/{name}`	PATCH	Updates and renames a document property.
`rest/projectdoc/1/document/{id}/property/{name}`	POST	Adds a property to a document.
`rest/projectdoc/1/document/{id}/section/{name}`	DELETE	Deletes a section from a projectdoc document.
`rest/projectdoc/1/document/{id}/section/{name}`	GET	Provides read access to a projectdoc document section.
`rest/projectdoc/1/document/{id}/section/{name}`	PATCH	Updates and renames a section of a projectdoc document.
`rest/projectdoc/1/document/{id}/section/{name}`	POST	Adds a section to a projectdoc document.
`rest/projectdoc/1/i18n/map`	GET	Generate a resource bundle with translations for a given set of keys.
`rest/projectdoc/1/service/csv-document`	POST	Runs an update on a single projectdoc document based on an uploaded file. The information will patch the existing document or create a new one if the document does not exist.
`rest/projectdoc/1/service/csv-table`	POST	Runs a bulk update based on a uploaded file. The information will patch existing files and create new ones.
`rest/projectdoc/1/service/document-create-facade`	POST	Creates a new projectdoc document based on a doctype, name, and short description.
`rest/projectdoc/1/service/document-create-hierarchy`	POST	Creates a hierarchy of documents based on the posted document.

Accessing the API

There are different approaches to access the web API provided by the projectdoc Toolbox via this extension.

REST API Browser

To use the REST API provided by the projectdoc Toolbox Online Manual or the Web API Extension use the Swagger UI that is installed with the app. The Swagger UI lets you easily explore and use the API from your web browser.

Note that the API Browser link to navigate to the Swagger UI is shown in the Administration Console. The Swagger UI can be accessed by any licensed user.

REST API Link for the projectdoc Toolbox

Selection of the REST API resources and services provided by the Web API Extension for the projectdoc Toolbox shown in the new Swagger UI

Userscripts

The Web API can be used with userscripts. Userscripts are typically short scripts that are executed in the user's browser.

Userscripts may be added to a browser by the use of a browser extension. Users selectively install and employ the scripts they want to execute in their browser.

You may also choose to deploy the userscripts to execute by the Confluence Administrators. The app Userscripts for Confluence (commercial license) is one option to integrate such userscripts easily.

Bookmarklets

The Bookmarklets Extension (free app) allows to integrate calls to the web API into the user's browser.

With bookmarklets services are brought to the fingertips of the users. The organization of bookmarks can be personalized very easily.

The Bookmarklets Extension provides a number of bookmarklets to get started. With the Bookmarklet Editor these bookmarklets can be loaded and installed. The editor also allows to create new bookmarklets.

An overview over projectdoc bookmarklets is available on Bookmarklets List Macro.

cURL

There are a lot of tools and programming libraries to use REST APIs.

cURL is one example to integrate information from projectdoc documents into remote information systems.

Logging

Logging is controlled by the package identifier de.smartics.projectdoc.extension.webapi.rest.

Version Tags

ETags are only supported for Confluence since version 5.10.x and version 1.1 of the web api.

Subordinate Topics

List of Services: Lists all services provided by the Web API Extension.

Resources

Related information on using REST APIs (with cURL) to integrate with remote information systems.

REST Login to Confluence with cURL: To access Confluence via its REST API with cURL you typically need to authenticate. Learn how to login with cURL and avoid some common security pitfalls.
Accessing projectdoc Properties with cURL: Learn how to access projectdoc properties via REST API with cURL.
projectdoc Bulk Changes to Documents: The Web API Extension for the projectdoc Toolbox can be employed to make bulk changes to documents. Since there is no safety net, these actions need to be take with care. This tip introduces a way to conduct this task.
Confluence as the Information Hub: Tools from the projectdoc Toolbox to import from and export to other information systems.
Import Resource: Provides services to import information from Maven artifacts into Confluence.