To assist in writing client applications that communicate with the CatDV Server API a JavaScript Library is included as part of the sample code bundled with CatDV Server.
This library makes use of jQuery to perform the HTTP calls to the server and to encode and decode the JSON messages.
Library Call Reference
The JavaScript library uses an asynchronous pattern. These functions do not, therefore, return values directly to the caller. Instead the caller provides one or two call-back functions.
The first function, the success call-back, is called if the operation was successful and is passed a single parameter containing the payload object returned by the server (the Reply envelope is stripped off by the library).
The second, optional failure call-back, is called if either the server returns an HTTP error, or if the call returns an ERROR status in the Reply. The failure call-back takes three parameters – the status, error message and payload from the reply. If this call-back is not supplied then a standard JavaScript alert is displayed.
Functions
registerLogInHandler(login_handler)
Register a call-back with the API that will be called if any API call returns an ‘AUTH’ status, indicating that the session has timed out. Typically this call-back should prompt to user to log in.
getSessionKey(success_callback, failure_callback)
Returns (via the success call-back) the current public RSA session key.
getSession(success_callback, failure_callback)
Returns (via the success call-back) the current public JSessionId and sets the JSESSIONID cookie.
login(username, encryptedPassword, success_callback, failure_callback)
Given the user name and an encrypted password establishes a secure, authenticated session with the server.
logout(success_callback, failure_callback)
Instructs the server to destroy the current session and discard the currently held credentials.
getClips(query, success_callback, failure_callback)
Returns (via the success call-back) a PartialResultSet containing the clips that match the filter in the query.
The query parameter is an object with the following fields
Field | Type | Description |
filter | String | Standard clip query as described in “Clip Query Filter Syntax” |
skip | Integer | Skip the first N results in the result set |
take | Integer | Return the N results after the skipped results. |
asc* | String | Column name to sort by in ascending order |
desc* | String | Column name to sort by in descending order |
* only one of ‘asc’ or ‘desc’ can be used in one call
getClip(clipId, success_callback, failure_callback)
Returns (via the success call-back) the clip with the specified id.
updateClip(clip, success_callback, failure_callback)
Takes a partially populated clip object, whose populated fields must include the ID, and updates those fields of the clip with that id on the server. Currently only a small number of fields are supported, but this will increase over time.