The Web Service API
This document describes the restful web service supplied with the WebPal Document Manager.
Web Service Location
The Web Service is available at
The input to all methods is XML text provided to the service in the body of an HTTP POST. The output is “text/xml” except for file downloads which returns the contents of a file with the appropriate mime type.
The input parameters can be passed either as attribute values of the root element, or as text or CDATA sections within elements whose tags are the parameter names.
For example, you can move and existing file with this request:
<?xml version="1.0" encoding="UTF-8"?><request command="move"
Alternatively, you can upload a new file like so:
<?xml version="1.0" encoding="UTF-8"?><request command="upload"
sessionID="bd7d8af5ab41407dac6666874c74c3ab"><dir><![CDATA[/dir/test1}}></dir><name><![CDATA[file1afddf}}></name><title><![CDATA[a document title}}></title><content><![CDATA[some text}}></content></request>
In the latter example, the command and session id are passed as attributes in the “request” element whereas the “dir”, “title”, and “content” are passed inside elements. The API method is always identified by the value of the parameter called “command”.
An example of the response XML is
<?xml version="1.0" encoding="UTF-8"?><response status="ok"><result><path>/dir/test1/file1afddf</path></result></response>
The root element is tagged with “response”. The status attribute will be “ok” on success, “fail” if an error occurs. The return values are enclosed in the element tagged with “result”.
If an error occurs, the error message will be in an “error” element in the response, for example:
<?xml version="1.0" encoding="UTF-8"?><response status="fail"><error>Bad path /dir/testb1</error></response>
In order to provide secure access, a client must first log into the web service. This is currently done through the “login” method, which takes a username and password as parameters. The method returns a session id which must be passed in as an argument to all subsequent calls.
There are two ways you can pass the session id to the service
- as the sessionID attribute of the Request element in the xml of the request
- as a HTTP header: X_DM_SESSION_ID
Paths and IDs
The name of the XML attribute that identifies a file or folder is path. This can be either
- The internal id of the file or folder in the form of a large integer
- If the pretty attribute is true (yes, true, 1), the pretty path of the document or folder relative to the logged in user’s shares.
Any boolean attribute is considered to be true if the value is a case insensitive match to “1”, “yes”, or “true”. It is considered false otherwise. The default value depends on the command.
Include Meta Data
Many of the file commands accept the boolean parameter “includeMetaData” which causes the result to include assorted file meta data.
Paging and Sort
Many of the commands that list WebPal items such as documents and folders or users accept parameters to control the position in the result set and number of items returned, analogous to the MySQL limit parameters:
- n or results - the number of items to return, default all records
- offset - the start position in the result set, default 0
- sort - a comma separated list of attribute names; the attribute name can be followed by a ‘:asc’ or ‘:desc’ to specify sort order
- type - if the kind of object being retrieved has a type attribute, this can be used to choose one of those types
Web Service API
All methods except login require a “sessionID” parameter. This will not be mentioned further in the following.
Many of the document manager commands return a list of zero or more paths. This is encoded in the XML as zero or more “path” elements contained within the result.