Learn how to access projectdoc space properties via REST API with cURL.
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.
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
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.
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
Now let us use this page ID in your first query:
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:
{
"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:
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
<?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:
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 '
{
"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
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
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.
