REST Interface V2
- Stefan Meissner
Quickstart: REST Upload
Docs come with a REST Interface for upload documents. This allows continuous delivery of documents using a continuous integration server such as Bamboo or Jenkins. So, documents can be kept on the latest version in Confluence.
REST URL for uploading a packaged doc (-javadoc.jar / .zip) and CREATE a new item in a specific category:
Method: PUT
URL: /rest/docs/2.0/repository/{CATEGORY_ID}/{DOC_NAME}
REST URL for uploading a packaged doc (-javadoc.jar / .zip) and UPDATE an existing item: Each document is identified by its unique key. The key consists of two alphanumeric strings separated by a dash (cxxxx-dxxxx).
Method: POST
URL: /rest/docs/2.0/repository/{DOC-KEY}
CURL Example
The following is a command-line sample of how to CREATE a Javadoc "lib-javadoc.jar" in the specific category with the identifier "c1075". The confluence installation is available at "http://confluence.example.org".
curl -u username:password --upload-file lib-javadoc.jar http://confluence.example.org/rest/docs/2.0/repository/c1075/testDoc
This sample demonstrates how to UPDATE an existing doc using the curl command. The value "c1075-d1082" in the URL is the key of the document to be updated.
curl -u username:password -X POST --upload-file javadoc.jar http://confluence.example.org/rest/docs/2.0/repository/c1001-d1004 -H "X-Atlassian-Token: no-check"
Watch the CURL-Upload Video: Confluence Docs Plugin 2.0
Python Script
This is a python sample of how to UPDATE a doc:
import sys
import base64
import httplib
import urllib
# get params
keyDoc = sys.argv[1]
docFile = sys.argv[2]
# server authentication
auth = base64.encodestring('%s:%s' % (username, password)).replace('\n', '')
headers = {"X-Atlassian-Token": "nocheck", "Authorization": "Basic %s" % auth, "Content-Type": "application/json"}
#update doc
conn = httplib.HTTPSConnection("confluence.example.org")
conn.request("POST", "/rest/docs/2.0/repository/" + keyDoc, open(docFile, "rb"), headers)
response = conn.getresponse()
conn.close()
# finished...
print response.status
print "-----"
print response.reason
Here, the corresponding command-line call for executing the python script above:
python scripts/docs-upload.py "c1075-d1082" "javadoc.jar"
Endpoints
The following is a list of all supported REST endpoints of the Docs Plugin.
Get Repository Details
Return a JSON object representing the menu structure of the docs repository.
Method: GET
URL: /rest/docs/2.0/repository/
Create Doc
Upload and create a new doc archive (.zip / .jar) under the defined category.
Method: PUT
URL: /rest/docs/2.0/repository/{categroy-id}/{doc-name}
Update Doc
Upload a doc archive (.zip / .jar) and UPDATE the specified (existing) doc.
Method: POST
URL: /rest/docs/2.0/repository/{doc-key}
Delete Doc
Delete a specific doc.
Method: DELETE
URL: /rest/docs/2.0/repository/{doc-key}
Rename Doc
Rename a doc.
Method: POST
URL: /rest/docs/2.0/repository/{doc-key}/{doc-name}
Load Doc Details
Get Details about a specific doc.
Method: GET
URL: /rest/docs/2.0/repository/{doc-key}
Load Category Details
Get Details about a specific Category.
Method: GET
URL: /rest/docs/2.0/repository/{category-id}
Create Category
Create a new category (menu item) in the repository.
Method: PUT
URL: /rest/docs/2.0/repository/{categroy-name}
Link Space Permission
Set a category SpaceKey for permission adjustments. (new in version 2.2)
Method: POST
URL: /rest/docs/2.0/repository/{categroy-id}/spacekey/{spaceKey}
Delete Category
Delete a category (menu item).
Method: DELETE
URL: /rest/docs/2.0/repository/{categroy-id}
Export Doc as ZIP Archive
Export doc as ZIP Archive. (new in version 2.5.3)
Method: GET
URL: /rest/docs/2.0/repository/archive/{doc-key}
Find Category by Name
Find all categories by name. (new in version 2.5.3)
Method: GET
URL: /rest/docs/2.0/repository/findByName/{name}
Find Doc in a Category by Name
Find all docs in a category by name. (new in version 2.5.3)
Method: GET
URL: /rest/docs/2.0/repository/{categroy-id}/findByName/{name}