API Endpoint Reference

by | Jan 21, 2015 | REST API |

BROWSE CATDV SUPPORT MANUALS

This section gives details of each API endpoint and details the methods supported, the parameters supported and the results that will be returned.

Endpoint: /session

Gives access to the current HTTP session.

GET /session?usr=<username>&pwd=<password>
GET /session?usr=<username>&epwd=<encrypted_password>

Returns the jSessionId of the current server session and sets the JSESSIONID cookie so that all subsequent calls attach to the authenticated session.

Parameter Type Description
usr String Username of authenticating user
pwd String Plain text password
epwd String RSA Encrypted password

In production environments is it always recommended that the encrypted form of this call is used. The encrypted password is sent as a base64 encoded representation of a standard RSA encrypted version of the plain text password using the public session key (see below).

GET /session/key

Returns a base64 encoded public key unique to this session that can be used to encrypt a plain text password before sending over the wire. See section “Password Encryption” for more details.

POST /session

To avoid user credentials appearing in a URL it is recommended that the POST method be used. The POST data should contain a JSON object with the following fields:

Property Type Description
username String Username of authenticating user
password String Plain text password
encryptedPassword String RSA Encrypted password

 DELETE /session

Ends the current session – logs out the user and frees one license.

Endpoint: /catalogs

Represents the collection of all catalogs on the server:

GET /catalogs

Returns an array of all the catalogs on the server.

GET /catalogs/<id>

Returns the catalog with the specified id

Endpoint: /clips

Represents the collection of all catalogs on the server:

GET /clips?filter=<filter>[&fetchRelated=<fetch_related>&include=<include>&skip=<skip>&take=<take>]

Returns a PartialResultSet of the clips that match the filter criteria. For details of the formats of the filter, fetch_related and include parameters see section “Clip Query Filter Syntax” for more details.

GET /clips?smartfolderID=<id>[&include=<include>&skip=<skip>&take=<take>]

Returns a PartialResultSet of the clips contained within the specified smart folder.

GET /clips?catalogID=<id>[&include=<include>&skip=<skip>&take=<take>]

Returns a PartialResultSet of the clips contained within the specified catalog.

GET /clips/<id>

Returns the clip with the specified id

PUT /clips/<id>

Update selected fields of the clip with the specified id. HTTP POST data should contain a partially populated clip object.

PUT /clips

Update multiple clips. There are two variants:

  1. HTTP POST data contains a single JSON Clip object but the ID field contains an array of IDs. In this case the same updates will applied to all the Clips specified by the list of IDs.
  2. HTTP POST data contains an array of JSON Clip objects, each containing an ID and any other fields to update, and the each update is applied in turn.

POST/clips

Add a new clip. The new clip must specify the catalogID for a valid, accessible catalog that the clip will be added to.

Writeable Clip Fields

The following clip fields can be set/updated:

  • catalogID
  • name
  • typeID
  • tape
  • notes
  • bin
  • status
  • marked
  • rating
  • clipRef
  • sourceMediaID
  • importSourceID
  • posterID
  • in/out and in2/out2
  • markers
  • user fields

In future versions of the API this set may be expanded.

Endpoint: /sourcemedia

Represents the collection of SourceMedia objects

GET /sourcemedia/<id>

Returns the SourceMedia object with the specified id.

GET /sourcemedia/<id>/thumbnails

Returns the thumbnails associated with the specified SourceMedia object.

Endpoint: /thumbnail

Gives access to individual thumbnails stored on the server:

GET /thumbnail/<id>

Returns the actual image data for the thumbnail with the specified id. The reply will have an appropriate MIME type such as image/jpeg.

Endpoint: /media

Gives access to the actual media stored on the server.

GET /media/<id>[?type=orig&download=true]

Returns the actual media data for the source media with the specified id. The reply will have an appropriate MIME type and can often be displayed directly by a browser. However, for video files it is usually necessary to create a specific media plug-in such as the QuickTime Player, and pass this URL of this endpoint to that.

Parameter Type Description
type proxy/orig Specifies whether to serve the original media (type=orig) or the proxy media (type=proxy). Defaults to proxy if not specified
download true/false If download=true then the endpoint serves the media with a MIME type of ‘application/octet-stream’ and a Content-Disposition of ‘attachment’. This will cause most browsers to prompt the user to save the content to a local file, rather than displaying the media itself.

NOTE: to access the media the caller must be in an authenticated session. If the media player being used does not inherit the browser’s cookies then it will be necessary to explicitly pass the JSessionID in the URL. This is done by appending the JSessionID to the URL separated with a semi-colon. For example

http://<catdv>/api/1/media/1234;jsessionid=CB2E8C4D09142DFFA416E7522

Endpoint: /smartfolders

Represents the collection of smart folders defined on the server

GET /smartfolders

Return the list of all the smart folders defined on the server.

GET /smartfolders/<id>

Return the specified smart folder

POST /smartfolders

Add a new smart folder to the system. The POST data must contain a JSON string representing the smart folder.

PUT /smartfolders/<id>

Update an existing, specified smart folder to the system. The POST data must contain a JSON string representing the updates to the smart folder. Only the fields that are to be changed need to be included.

 DELETE /smartfolders/<id>

Remove the specified smart folder from the system.