API DOCUMENTATION

NotreDAM provides a REST interface via HTTP. It allows users to create, edit and delete dam's objects like workspaces, items, metadata and so on through an other application. An api_key is requested for each application.

HTTP requests are submitted via both GET and POST, depending on the API method. Responses are returned in JSON format.

Authentication

Each API call needs authentication. Applications need three values for authenticating on NotreDAM:

  • api_key
  • user_id
  • secret

api_key is a unique string that identify the application which is calling NotreDAM. It means that applications must request their api_key, which will be sent via email (or via other channels...)

user_id is the identifier of the application user on NotreDAM.

secret is a hash value shared between the application and NotreDAM. secret is unique for each user application pair

In order to get the user_id and the secret key needed for authentication, you have to request them via POST (https?) at the following url:

/api/login/

passing:

  • api_key
  • user_name
  • password

The response is formatted in JSON. It returns:

  • user_id
  • secret
  • session_id

Except for the login, API methods must be called supplying three arguments,besides the ones typical of the given method:

  • api_key
  • user_id
  • checksum

checksum is a hash value computed from the request parameters and the secret, shared by NotreDAM and the calling application.

It is obtained in this way:

  • concatenate the argument name-value pair, inclunding api_key and user_id, e.g. :api_key=1, user_id=1, foo=1, bar=2 => ['foo1', 'bar2', 'api_key1', 'user_id1']
  • sort the list of arguments obtained into alphabetical order: 
l = ['foo1', 'bar2', 'api_key1', 'user_id1']
l.sort()
  • then concatenate the shared secret and the argument name-value pairs, e.g. 
s = SECRET + ''.join(l)
  • calculate the sha1() hash of this string 
from hashlib import sha1
checksum = sha1(s).hexdigest()
  • append this value to the argument list with the name 'checksum'. So, the final arguments list will be: 
api_key=1&user_id=1&foo=1&bar=2&checksum=8b04574ab4686cb024bdb7e46a9c933a511e4299

API METHODS

Workspaces

Items

Keywords

Smart Folders

Renditions

Scripts

States

Authentication

Admin

The following methods are not public, and can be called from superuser only.

Knowledge base

The following URLs do not use the API key, but the standard HTTP authentication methods.

Some of the following URLs support the HTTP PUT and DELETE methods, for creating or deleting resources. Those methods can be "aliased" with HTTP POST by adding a special variable to the URL, called __REAL_HTTP_METHOD__, containing either "PUT" or "DELETE". For example: http://dam.com/api/workspace/1/kb/object?__REAL_HTTP_METHOD__=PUT