Accessing projectdoc Properties with cURL

Versions Compared

Old Version 4

changes.mady.by.user Anton Kronseder

Saved on 15. Sep 2016

compared with

New Version Current

changes.mady.by.user Robert Reiner

Saved on 31. Jul 2017

Key

This line was added.
This line was removed.
Formatting was changed.

Section

Column

Document Properties Marker

override	false

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


Doctype	topic	hide
Name	Accessing projectdoc Properties with cURL

Parent

Parent Property

property	Parent
property-name	Name

Audience

Name List

doctype	role
render-no-hits-as-blank	true
render-list-as-comma-separated-values	true
names	Author, Documentation Architect, Documentation Gardener
property	Audience
empty-as-none	false

Level of Experience

Name List

doctype	experience-level
render-no-hits-as-blank	true
names	Advanced Beginner
property	Level of Experience
empty-as-none	false

Expected Duration

15 min

Subject

Name List

doctype	subject
property	Subject

Sponsors

Name List

doctype	stakeholder
render-no-hits-as-blank	true
property	Sponsors


Sort Key		hide

Column

width	45%

Panel

title	Contents

Table of Contents

maxLevel	2
indent	15px
style	none

...

Section

title	Prerequisites

Section

title	Install cURL

Download and install cURL.

Tip Box

title	Use apt

On ubuntu use:

Code Block
apt-get install curl

Section

title	Install the projectdoc Web API Extension

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

Section

Column

width	50%

Panel

title	Optional

Section

title	Learn how to Login to Confluence with cURL

Display Property

document	REST Login to Confluence with cURL
property-name	Short Description

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

Column

width	50%

Panel

title	Optional

Section

title	Install XML Commandline Tool

xmlstarlet may be helpful to enhance the readability and for further processing of XML responses from the REST API.

Section

Column

width	50%

Panel

title	Optional

Section

title	Install JSON Processor

These additional tools may be helpful to enhance the readability and for further processing of JSON responses from the REST API:

JQ a lightweight and flexible command-line JSON processor
python (e.g. see: Parsing JSON from command line using Python)

Column

width	50%

Panel

title	Optional

Section

title	Install Perl

install Perl using:

apt-get install perl

if you want to use urlencode to encode URLs containing special characters.

Some other solutions are discussed here: how to urlencode data for curl command

Section

title	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 and at least created a simple projectdoc document.

Section

title	Query the Properties of a projectdoc Document

Query a newly created projectdoc document for its properties. To build such a query you need the ID of the projectdoc document. An easy way to get the ID of a document is to navigate to the Confluence page, since the page ID matches the document ID. Use the Confluence search and than click the "Page Information" action from the menu and copy the page ID from the URL:

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

Note Box
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:

Code Block Placeholder

code-theme	Midnight
code-language	Bash
code-title	Query the properties of a projectdoc document

curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property

Here you can see the response:

Code Block Placeholder

code-theme	SpaceDefault
code-language	Bash
code-title	Response

 {"id":123456789,"property":[{"name":"Doctype","value":"homepage"},{"name":"Name","value":"ManualTests Home"},{"name":"Short Description","value":"homepage"},{"name":"Tags","value":""},{"name":"use-confluence-macro-style","value":"false"},{"name":"name-list-default-boxstyle","value":"true"},{"name":"name-list-aaabb-boxstyle","value":"false"},{"name":"Creation Date","value":"22 Dec 2015"},{"name":"Creation Timestamp","value":"0000001450780454000"},{"name":"Creator","value":"anton.kronseder"},{"name":"Title","value":"ManualTests Home"},{"name":"Space Key","value":"MAN"},{"name":"Space Title","value":"ManualTests Home"},{"name":"Last Modification Date","value":"22 Dec 2015"},{"name":"Last Modification Timestamp","value":"0000001457108295000"},{"name":"Page ID","value":"4653082"},{"name":"Last Modifier","value":"anton.kronseder"},{"name":"Wiki Type","value":"page"},{"name":"Creation Date Timestamp","value":"0000001450738800000"},{"name":"Creation Date$","value":"22 Dec 2015"},{"name":"Creation Date§","value":"20151222"},{"name":"Last Modification Date Timestamp","value":"0000001450738800000"},{"name":"Last Modification Date$","value":"22 Dec 2015"},{"name":"Last Modification Date§","value":"20151222"},{"name":"Sort Key","value":"ManualTests Home"},{"name":"Index Key","value":"M"},{"name":"VersionHistory","value":"anton.kronseder:2016-03-04, anton.kronseder:2015-12-22"},{"name":"DocumentPropertyRefs","value":""},{"name":"Relative URL","value":"/display/MAN/ManualTests+Home"},{"name":"URL","value":"https://www.example.com/confluence/display/MAN/ManualTests+Home"},{"name":"Tiny URL","value":"https://www.example.com/confluence/x/GgBH"}]}

Now let us prettify the the response by sending the response to jq:

Code Block Placeholder

code-theme	Midnight
code-language	Bash
code-title	Query the properties of a projectdoc document (pretty)

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

Code Block Placeholder

code-theme	SpaceDefault
code-language	Bash
code-title	Response (pretty)

 {
  "id": 123456789,
  "property": [
    {
      "name": "Doctype",
      "value": "homepage"
    },
...
  ]
}

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

Code Block Placeholder

code-theme	Midnight
code-language	Bash
code-title	Query the properties of a projectdoc document (xml)

curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789?expand=property
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.xml?expand=property

Code Block Placeholder

code-theme	SpaceDefault
code-language	Bash
code-title	Response (xml)

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?><document id="123456789"><property><name>Doctype</name><value>homepage</value></property><property><name>Name</name><value>ManualTests Home</value></property><property><name>Short Description</name><value>homepage</value></property><property><name>Tags</name><value></value></property><property><name>use-confluence-macro-style</name><value>false</value></property><property><name>name-list-default-boxstyle</name><value>true</value></property><property><name>name-list-aaabb-boxstyle</name><value>false</value></property><property><name>Creation Date</name><value>22 Dec 2015</value></property><property><name>Creation Timestamp</name><value>0000001450780454000</value></property><property><name>Creator</name><value>anton.kronseder</value></property><property><name>Title</name><value>ManualTests Home</value></property><property><name>Space Key</name><value>MAN</value></property><property><name>Space Title</name><value>ManualTests Home</value></property><property><name>Last Modification Date</name><value>22 Dec 2015</value></property><property><name>Last Modification Timestamp</name><value>0000001457108295000</value></property><property><name>Page ID</name><value>4653082</value></property><property><name>Last Modifier</name><value>anton.kronseder</value></property><property><name>Wiki Type</name><value>page</value></property><property><name>Creation Date Timestamp</name><value>0000001450738800000</value></property><property><name>Creation Date$</name><value>22 Dec 2015</value></property><property><name>Creation Date§</name><value>20151222</value></property><property><name>Last Modification Date Timestamp</name><value>0000001450738800000</value></property><property><name>Last Modification Date$</name><value>22 Dec 2015</value></property><property><name>Last Modification Date§</name><value>20151222</value></property><property><name>Sort Key</name><value>ManualTests Home</value></property><property><name>Index Key</name><value>M</value></property><property><name>VersionHistory</name><value>anton.kronseder:2016-03-04, anton.kronseder:2015-12-22</value></property><property><name>DocumentPropertyRefs</name><value></value></property><property><name>Relative URL</name><value>/display/MAN/ManualTests+Home</value></property><property><name>URL</name><value>https://www.example.com/confluence/display/MAN/ManualTests+Home</value></property><property><name>Tiny URL</name><value>https://www.example.com/confluence/x/GgBH</value></property></document>

In conjunction with xmlstarlet you can also prettyprint it:

Code Block Placeholder

code-theme	Midnight
code-language	Bash
code-title	Query the properties of a projectdoc document (xml \| pretty)

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

Code Block Placeholder

code-theme	SpaceDefault
code-language	Bash
code-title	Response (xml \| pretty)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<document id="123456789">
 <property>
 <name>Doctype</name>
 <value>homepage</value>
 </property>
 <property>
 <name>Name</name>
 <value>ManualTests Home</value>
 </property>
 <property>
 <name>Short Description</name>
 <value>homepage</value>
 </property>...</document>

Section

title	Receiving Property Names, Values or both

Receiving only the property names or values or even both is very easy using jq for JSON:

Code Block Placeholder

code-theme	Midnight
code-language	Bash
code-title	Query the properties of a projectdoc document (pretty)

curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property | jq .property[].name
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property | jq .property[].value
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789.json?expand=property | jq .property[].

Code Block Placeholder

code-theme	SpaceDefault
code-language	Bash
code-title	Responses

Names:
 
"Doctype"
"Name"
"Short Description"
...
 
Values:
 
"homepage"
"ManualTests Home"
"homepage"
...
 
Names and Values:
 
{
  "name": "Doctype",
  "value": "homepage"
}
...

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

Code Block Placeholder

code-theme	Midnight
code-language	Bash
code-title	Query the properties of a projectdoc document (pretty)

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

Code Block Placeholder

code-theme	SpaceDefault
code-language	Bash
code-title	Response

{
 "Doctype": "homepage",
 "Name": "ManualTests Home",
 "Short Description": "homepage",
 "Tags": "",
 ...
}

Section

title	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

Code Block Placeholder

code-theme	Midnight
code-language	Bash
code-title	Receive a single property

curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/Doctype.json?expand=property | jq .
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/Doctype.json?expand=property | jq .value
or
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/Doctype.json?expand=property | jq -r .value

Code Block Placeholder

code-theme	SpaceDefault
code-language	Bash
code-title	Responses

Full property:
 
{
  "name": "Short Description",
  "value": "homepage",
  "document-id": 123456789
}


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

If the property (key) contains special characters which can not be part of an URL, they have to be escaped. For example see how the property "Short Description" is retrieved:

Code Block Placeholder

code-theme	Midnight
code-language	Bash
code-title	Receive a single property with special chars

curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/Short%20Description.json?expand=property | jq .
 
or using a variable in conjunction with perl:
 
property="$(perl -MURI::Escape -e 'print uri_escape($ARGV[0]);'  "Short Description")"
curl -s --cookie /tmp/confluence.cookie \
	https://www.example.com/confluence/rest/projectdoc/1/document/123456789/property/${property}.json?expand=property | jq .

Code Block Placeholder

code-theme	SpaceDefault
code-language	Bash
code-title	Response

{
  "name": "Short Description",
  "value": "homepage",
  "document-id": 12456789
}

Section

title	Resumé

Section

title	Subordinate Topics

Display Table

doctype	topic
render-no-hits-as-blank	true
select	Name, Short Description
restrict-to-immediate-children	true
sort-by	Sort Key, Name

...

Section

title	References

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

Section

title	Resources

Tour

render-as-definition-list	true
replace-title-with-name	true

Title	Short Description
Accessing projectdoc Space Properties with cURL
REST Login to Confluence with cURL

Piwik Set Multiple Custom Variables

Name	Value
Department	projectdoc
Category	projectdoc-tip
Type	howto

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

Versions Compared

Old Version 4

New Version Current

Key

About

Keep up-to-date!

Powered by