Versions Compared

Key

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

...

Section
titleExecuting 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
titleQuery 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 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-themeMidnight
code-languageBash
code-titleQuery 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-themeSpaceDefault
code-languageBash
code-titleResponse
 {"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-themeMidnight
code-languageBash
code-titleQuery 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-themeSpaceDefault
code-languageBash
code-titleResponse (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-themeMidnight
code-languageBash
code-titleQuery 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-themeSpaceDefault
code-languageBash
code-titleResponse (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-themeMidnight
code-languageBash
code-titleQuery 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-themeSpaceDefault
code-languageBash
code-titleResponse (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
titleReceiving 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-themeMidnight
code-languageBash
code-titleQuery 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-themeSpaceDefault
code-languageBash
code-titleResponses
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-themeMidnight
code-languageBash
code-titleQuery 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-themeSpaceDefault
code-languageBash
code-titleResponse
{
 "Doctype": "homepage",
 "Name": "ManualTests Home",
 "Short Description": "homepage",
 "Tags": "",
 ...
}
Section
titleReceive 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-themeMidnight
code-languageBash
code-titleReceive 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-themeSpaceDefault
code-languageBash
code-titleResponses
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-themeMidnight
code-languageBash
code-titleReceive 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-themeSpaceDefault
code-languageBash
code-titleResponse
{
  "name": "Short Description",
  "value": "homepage",
  "document-id": 12456789
}

...