Worksnaps API Documentation

Introduction

Worksnaps APIs are used for external programs or applications to integrate with Worksnaps.

Your Worksnaps subscription includes API access for all accounts (including free and trial accounts) which can be used to manage your Worksnaps account.

Some typical examples for using Worksnaps API are :

Example 1 -- An external program uses the APIs to retrieve the time logged in Worksnaps to generate reports.
Example 2 -- Another SaaS service bundles Worksnaps to allow its users to use Worksnaps Client to track time while its back-end uses the Worksnaps APIs to fetch and display the time and work information within its own service.
Example 3 -- An Worksnaps customer uses the API to automatically create projects and tasks based on the workflow in another system.

Authentication

Worksnaps API calls are implemented as XML over HTTP using REST semantics. The API supports four verbs represented by the four HTTP request actions: GET, POST, PUT and DELETE.

GET is used to read a single object, retrieve a list of objects, or generate data reports.
POST is used to create a new object.
PUT is used to update a existing object.
DELETE is used to delete an existing object.

Every user has an API token and authentication is managed using HTTP basic authentication. In each request the API token has to be included as the username and the password is ignored (that is, only the API token is used for authenticating API requests). Example,

curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' -u hy192jfeh26uiew8yg43mfekb21jfenaxop912f3:ignored -d '<request>...</request>'

A user's API token can be retrieved from the web site after the user logs in and go to Profile & Settings >> Web Service API. The application that uses the API should securely store the API token.

For some operations, such as user creation, they are considered to be privileged operations which are only allowed for trusted applications, such as a partner system. In this case, when issuing these API calls, a partner API token needs to be used instead of an end user's API token.

The partner API token is established out-of-band as a secret between Worksnaps and a partner.

Standard Return Code

For various operations, standard HTTP status codes are returned. We list the these standard return code here so that we will not repeat them in the API documentation.

All Requests

400 (Bad Request)	The request could not be understood due to malformed syntax or incorrect parameters
401 (Unauthorized)	the user did not provide a valid authentication token
403 (Forbidden)	the user is not allowed to perform the operation
404 (Not Found)	the requested resource is not found
500 (Server Error)	the server encounters an error when processing the request

GET

200 (OK)

the operation is successful and a reply is returned

POST

201 (Created)	the operation is successful and the object is created
422 (Unprocessable Entity)	the request is valid but the object cannot be created (for example, due to duplicated unique key)

PUT

200 (OK)	the operation is successful and the object is updated
422 (Unprocessable Entity)	the request is valid but the object cannot be updated (for example, due to duplicated unique key)

DELETE

200 (OK)

the operation is successful and the object is deleted

Extra Error Information

In the case of an error, extra error information will be provided as part of the reply payload. The reply is in the following format.

<reply>
<status type="integer">0</status>
<error_code type="integer">#{error_code}</error_code>
<error_string>#{error_string}</error_string>
</reply>

For example, a user tries to create a project but a project created by him with the same name already exists. In addition to 422 return code, the following reply will be returned.

<reply>
<status type="integer">0</status>
<error_code type="integer">10022</error_code>
<error_string>A project of name Website Design already exists</error_string>
</reply>