REST Interface V1 (deprecated)

!! DEPRECATION NOTE !!

Up from Docs Version 2.x this REST Interface is not longer supported. Please see REST Interface V2 !!

Quickstart: REST Upload

Besides the manual organization of your documentations, Docs also provides a REST interface in order to automate the publishing process. This feature enables you to keep your documents easily up to date. For example, you can include document publishing in your Continuous Integration process.

REST URL for uploading packaged (-javadoc.jar / .zip) docs:

Method:    PUT
URL:       /rest/docs/1.0/repository/{categroy}/{docname}

In order to upload new documentation, you can PUT *-javadoc.jar files or other zipped HTML and javascript-based documentation against this URL. Each documentation requires an "index.htm" or "index.html" file as the main entry point.

If the category or docName doesn't exist, the server will create a new category or docName during the upload process. In case the docName does already exist, the documentation is going to be overwritten.

CURL Sample

Here is a simple command-line call on how to upload the Javadoc "JDFLibJ-2.1.5.86-javadoc.jar" to Docs. The confluence installation is available under "http://confluence.example.org". You need to be authenticated when uploading new doc archives. Curl provides the parameter "-u {username}:{password}" in order to become authenticated.

curl -u username:password --upload JDFLibJ-2.1.5.86-javadoc.jar http://confluence.example.org/rest/docs/1.0/repository/myCategory/myDoc

Watch the CURL-Upload Video: Confluence Docs Plugin - Upload via curl

Python Script

You can also use python in order to publish your documentation. The following is a sample of a python script:

import sys
import base64
import httplib
import urllib

# get params
category = sys.argv[1]
docName = sys.argv[2]
docFile = sys.argv[3]

username = "username"
password = "password"

# server authentication
auth = base64.encodestring('%s:%s' % (username, password)).replace('\n', '')
headers = {"X-Atlassian-Token": "nocheck", "Authorization": "Basic %s" % auth, "Content-Type": "application/json"}

#upload doc
category = urllib.quote(category, '')
docName = urllib.quote(docName, '')

conn = httplib.HTTPSConnection("confluence.example.org")
conn.request("PUT", "/rest/docs/1.0/repository/" + category + "/" + docName, open(docFile, "rb"), headers)
response = conn.getresponse()
conn.close()

# finished...
print response.status
print "-----"  
print response.reason

Finally, the corresponding command-line call for executing the python script:

python scripts/docs-upload.py "CATEGROY" "DOC-NAME" "javadoc.jar"

Full REST Interface

The following is a list of all supported REST calls.

Get Repository Details

Returns a JSON object representing the menu structure of the docs repository.

Method:    GET
URL:       /rest/docs/1.0/repository/

Upload Doc

Uploads a new documentation zip/jar archive under the defined category.

Method:    PUT
URL:       /rest/docs/1.0/repository/{categroy}/{docname}

Create Category

Create a new category (menu item) in the docs repository.

Method:    PUT
URL:       /rest/docs/1.0/repository/{categroy}

Rename Doc

Rename a doc in the docs repository.

Method:    POST
URL:       /rest/docs/1.0/repository/{category}/{currentName}/rename/{newName}

Delete Document

Remove a specific document from the docs repository.

Method:    DELETE
URL:       /rest/docs/1.0/repository/{category}/{docname}

Delete Category

Remove a specific category including all containing docs from the docs repository.

Method:    DELETE
URL:       /rest/docs/1.0/repository/{category}