projectdoc Toolbox

Accessing projectdoc Space Properties with cURL

Learn how to access projectdoc space properties via REST API with cURL.

Parent: Tips
Audience: Author, Documentation Architect, Documentation Gardener
Level of Experience: Advanced Beginner
Expected Duration: 15 min
Tags: Confluence, curl, property, REST, Space
Type: Tip

Contents

projectdoc spaces provide properties via the Document Properties Marker Macro. This is analogue to projectdoc documents providing properties as described in the tip Accessing projectdoc Space Properties with cURL.

The projectdoc Toolbox allows to define properties that are visible within spaces. This is useful if you want to refer to the value of a property from any page within a space. A typical use case is that you define a property to store the version of a product you are documenting in that space. Whenever you need to refer to the current version, you use a macro to fetch this information. Therefore there are also use cases where teams want to access these properties from other information systems per REST.

If you want to access a property from one of your Maven projects, import it as a confluence space using the free Maven Extension (marketplace link) for projectdoc. Now all important maven properties and other information residing in your pom can be accessed as space properties or page properties.

This tip will help you making the first steps using cURL from the command-line to access these properties.

The projectdoc Web API Extension provides REST resources which can be queried using REST API calls via cURL (a command-line tool for transferring data using various protocols).

Prerequisites

Install cURL

Download and install cURL.

Use apt

On ubuntu use:

apt-get install curl

Install the projectdoc Web API Extension

To use the REST API for the projectdoc Toolbox you have to install the Web API Extension for Confluence. The Web API Extension is available on the Atlassian Marketplace.

Optional

Learn how to 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.

Read REST Login to Confluence with cURL to learn how to login using cURL.

Optional

Learn how to Access projectdoc Properties with cURL

Read the tip Accessing projectdoc Space Properties with cURL to make the first steps accessing properties.

Executing REST Calls

After having installed the projectdoc Web API Extension to your Confluence instance choose a login method and start using the REST API. All the following examples use a cookie based login but feel free to take another choice.

This section will provide some examples how to get you started.

Let's assume you have already created a projectdoc workspace .

Query the Properties of a projectdoc Space

Query the newly created projectdoc space for its properties. To build such a query you need the space key of the space. Just choose "Overview" of the "Space tools" actions and retrieve it from the overview page.

Another option is to use the following JavaScript command in the console of your browser: AJS.params.spaceKey

This tip addresses all Web API Extension versions since 1.0. Starting with Version 1.1 it is mandatory to use the request parameter expand=property to retrieve properties. For older versions this property does not exist.

Now let us use this page ID in your first query:

Query the properties of a projectdoc document

curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/space/home.json?expand=property | jq.

Here you can see the response:

Response

 {
  "id": 950274,
  "property": [
    {
      "source": "IDX",
      "name": "Categories",
      "value": ""
    },
    {
      "source": "IDX",
      "name": "documentation-json-uri",
      "value": "https://www.smartics.eu/confluence/download/attachments/12156954/docmap.json?api=v2"
    },
...

Besides JSON you can also get the response as XML. Just omit the extension or use .xml as extension:

Query the properties of a projectdoc document (xml)

curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/space/home?expand=property | xmlstarlet  format --indent-tab
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/space/home.xml?expand=property | xmlstarlet  format --indent-tab

Response (xml)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<space id="950274">
        <property>
                <source>IDX</source>
                <name>Categories</name>
                <value/>
        </property>
        <property>
                <source>IDX</source>
                <name>documentation-json-uri</name>
                <value>https://www.smartics.eu/confluence/download/attachments/12156954/docmap.json?api=v2</value>
        </property>
...

Receiving Property Names, Values or both

If you would like to receive the values in a compact form use the following expression:

Query the properties of a projectdoc document (pretty)

curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/space/home.json?expand=property | \
	jq   '[.property[] | { key : .name , value: .value}] | from_entries '

Response

{
  "Categories": "",
  "documentation-json-uri": "https://www.smartics.eu/confluence/download/attachments/12156954/docmap.json?api=v2",
  "DocumentPropertyRefs": "",
  "extract-short-description-from-metadata-table": "true",
  ...
}

Other possibilities are analogue to Accessing projectdoc Properties with cURL.

Receive a single Property

Receiving only one property by accessing it explicitly (instead of filtering for it).

get the full property
get only the value
get the value without quotes

Receive a single property

curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/space/home/property/extract-short-description-from-metadata-table.json?expand=property | jq .
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/space/home/property/extract-short-description-from-metadata-table.json?expand=property | jq .value
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/space/home/property/extract-short-description-from-metadata-table.json?expand=property | jq -r .value

Responses

Full property:
 
{
  "source": "IDX",
  "name": "extract-short-description-from-metadata-table",
  "value": "true"
}

Only the value:
 
"true"
 
The value without quotes:
 
true

If the property (key) contains special characters which can not be part of an URL, they have to be escaped. For an example see how we solved this in the tip Accessing projectdoc Properties with cURL.

References

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.
REST API Browser - Confluence Built-in API client to execute available methods and examine responses.
Confluence REST API Examples - This page contains examples of using the Confluence Content REST API using curl
JQ - a lightweight and flexible command-line JSON processor
xmlstarlet - Command Line XML Toolkit

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal