The Web Service API



Introduction

This document describes the restful web service supplied with the WebPal Document Manager.

Web Service Location

The Web Service is available at

https://MYSERVER.webpal.net/webservice/xml-service.php

Requests

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"
    path="/dir/test1/file1"
    dir="/dir/testb1/testc1"
    sessionID="bd7d8af5ab41407dac6666874c74c3ab"/>

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”.

Responses

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>

Authentication

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

  1. as the sessionID attribute of the Request element in the xml of the request
  2. 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

  1. The internal id of the file or folder in the form of a large integer
  2. 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.

Booleans

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.

 

POST batch

name type required? description
sessionID string true

POST copy

name type required? description
sessionID string true

POST createFolder

name type required? description
sessionID string true

POST createOrUpdateUser

(admin only for now) Request XML specifies property value mapping (see below) - user is identified by email or login and updated or created as necessary. To change groups, specify the property “groupNames” as a comma separated list of group names. Update of existing user is done only if “allowUpdate’ is true. If “createDrive” is true, a drive is in created in Users

name type required? description
allowUpdate boolean false If true, allows changes to existing user; otherwise only create user.
id int false id field of internal user record.
login string true identifies the user to update or a new login to create
email string false User's primary email address. Note - used for password retrieval.
email2 string false
firstname string false first name
lastname string false last name
role string false "admin" or "user" or "guest"
groupNames string false Comma-separated list of group names to assign to the user. Replaces existing groups. If a group name does not exist, fails unless "createGroups" is true.
createGroups boolean false Allow unknown groups in groupNames, creates a group for each of those names.
role string false
password string false
activate boolean false
createDrive boolean false
copyGuestUserShares boolean false
phone string false
cell string false
fax string false
address1 string false
city string false
province string false
postalcode string false
lang string false Two letter code, used in WebPal UI to choose translations

POST createSystemShare

name type required? description

POST delete

name type required? description
sessionID string true

POST download

name type required? description

POST exists

name type required? description
sessionID string true

POST fetchUserProfile

Retrieves meta information about a user. Optional parameter is “user_id” (database id of user), signed in user must be an admin or the same as the specified user; Returns an XML structure identifying the key/value pairs in the profile

name type required? description

POST fileCount

name type required? description
sessionID string true

POST fileInfo

name type required? description
sessionID string true

POST generateThumbnails

name type required? description

POST getPrettyName

name type required? description
sessionID string true

POST hasThumbnail

name type required? description
sessionID string true

POST icon

name type required? description

POST index

name type required? description
sessionID string true

POST listActivity

name type required? description

POST listDirectory

name type required? description
sessionID string true

POST listGroups

name type required? description

POST listRootContents

name type required? description
sessionID string true

POST listRoots

Returns a list of paths to identify the system shares for the logged in user.+

name type required? description
sessionID string true

Request:

<?xml version="1.0" encoding="UTF-8"?><request command="listRoots" 
    sessionID="bd7d8af5ab41407dac6666874c74c3ab"/>

Response:

<?xml version="1.0" encoding="utf-8"?><response status="ok"><result><path>2524845877563804</path></result></response>

 

POST listUsers

name type required? description
sessionID string true

POST login

Establishes a session with the WebPal Server. The parameters are user and password. Returns sessionID.

name type required? description
user string true unique login/username
password string true password, in plain text

<?xml version="1.0" encoding="UTF-8"?> <response status="ok"> <sessionID>bd7d8af5ab41407dac6666874c74c3ab</sessionID> </response>

Request:

<?xml version="1.0" encoding="UTF-8"?><request command="login"
        user="myUsername"
        password="myPassword"/>

Response:

<?xml version="1.0" encoding="UTF-8"?><response status="ok"><sessionID>bd7d8af5ab41407dac6666874c74c3ab</sessionID></response>

POST logout

If a session id is supplied, will end that session. This does nothing otherwise.

name type required? description
sessionID string true

Request:

<?xml version="1.0" encoding="UTF-8"?><request command="logout" 
    sessionID="bd7d8af5ab41407dac6666874c74c3ab"/>

Response:

<?xml version="1.0" encoding="utf-8"?><response status="ok"/>

POST lookupPretty

name type required? description
sessionID string true

POST metaData

name type required? description
sessionID string true

POST move

name type required? description
sessionID string true

POST noMatchingUser

name type required? description
sessionID string true

POST pdf

name type required? description

POST permissions

name type required? description
sessionID string true

POST ping

name type required? description
userid string false

POST recentActivity

name type required? description

POST recentlyAdded

This has no parameters. Returns the list of recently added files ordered from most recent to oldest.

name type required? description

Request:

<?xml version="1.0" encoding="UTF-8"?><request command="recentlyAdded" 
    sessionID="bd7d8af5ab41407dac6666874c74c3ab"/>

Response:

<?xml version="1.0" encoding="utf-8"?><response status="ok"><result><path>9023595553956981</path><path>3878646746527564</path><path>9088757550083894</path><path>7779917503869748</path><path>7392023489221651</path><path>5205956563870260</path><path>8403445861313204</path><path>4536257862475081</path><path>6863613407673713</path><path>2725473575735027</path></result></response>

Note that the documents are identified by their internal ids.

 

POST recentlyAddedInFolder

name type required? description

POST recentlyUploaded

name type required? description

POST rename

name type required? description
sessionID string true

POST resetPassword

name type required? description

POST search

POST setMetaData

name type required? description
sessionID string true

POST share

name type required? description

POST thumbnail

name type required? description

POST thumbnailOrImage

name type required? description

POST toPDF

name type required? description

POST updateUserProfile

optional parameter is “user_id” (database id of user), signed in user must be an admin or the same as the specified user; Request XML specifies property value mapping in “set” elements

name type required? description

POST upload

name type required? description
sessionID string true

POST userExists

admin only, given one of a user id in the “login” parameter or an email address in the “email” parameter, checks if a user with that login or email exists

name type required? description

POST userFile

name type required? description
sessionID string true

POST userInfo

optional parameter is “login” (actually must be the database id of the user), signed in user must be an admin or the same as the specified user; returns some basic information about the user

name type required? description

POST userShares

name type required? description

POST viewerLink