REST API Introduction

CatDV Server supports a comprehensive RESTful API that allows third party integrators to access data stored within CatDV Server directly through a simple HTTP-based API.

REST (REpresentational State Transfer) is a design pattern for modern web-based APIs that represents the data held by a system (its state’) as a URL namespace, where each item of data has a unique URL. Operations on these data are performed by making standard HTTP requests, with the operation specified by the standard HTTP ‘verbs’ GET, POST, PUT and DELETE.

The CatDV Server REST API provides full access to the functionality of CatDV Server. The CatDV Web Interface (including the administration function) and other components – such as the CatDV Premiere Panel, the CatDV Final Cut Server plugin – all exclusively use the REST API to implement the features they provide. Therefore anything that can be done with any of these components can be achieved by a third party component via the REST API.

Licensing

Please note that to use the REST API you must have a CatDV Web Client license for the appropriate number of sessions. Each web browser or other client application that connects to the CatDV Server using the REST API counts as one concurrent user of the license.

You are not permitted to “multiplex” connections in your code so that multiple users all share a single session.

Use of the REST API indicates your agreement of the above condition. In exceptional circumstances, adjustments to this rule may be allowed in which case we will provide written approval to break this rule. Please contact us if you wish to discuss a specific workflow.

Getting Started

Starting with version 6.8, CatDV Server now incorporates an integrated web server that, by default, listens on port 8080. The REST API is accessed through a set of URLs that begin ‘api’. For example to query the configuration of the server you could type the following into your browser address bar:

http://<catdv_server_hostname>:8080/catdv/api/info

This should return basic information about the server:

{ "status": "OK", "apiVersion": 9, "data":{ "version":"CatDV Web Interface 7.0 …”, "status":" Web Client and Web Services running", "details": … } }

The data returned is in JavaScript Object Notation (JSON). Like all the replies from the REST API it consists of some data wrapped in a simple Reply object. The Reply object has three properties:

· status - Status possible values are OK, ERROR or AUTH

· apiVersion – the version of the REST API implemented by this server

· data - for successful calls contains the actual data

· errorMessage - for ERROR replies contains details of the error

NOTE: In future example URLs the server address, port and leading /catdv part of the URL will be omitted, so this URL would become simply:

/api/info

API Version

The ‘info’ call is unique in that it does not require a version number to be specified. All other calls to the REST API take the form:

/api/<version_number>/<endpoint>

The current version number implemented by the server is reported by the /api/info call.

Authentication

The ‘info’ call is also unusual in that it does not require an authenticated session. For example if you try to get a list of the catalogs on the server:

/api/9/catalogs

You will receive the following reply from the server:

{"status":"AUTH", "errorMessage":"Authentication Required"}

To access this API endpoint, you must first establish an authenticated session. You do this through the ‘session’ endpoint:

/api/9/session?usr=fred&pwd=secret

Which, assuming the username and password were correct would return:

{"status":"OK", "data":{"jsessionid":"0580BD2E56AF629615CE042BB1ECAA59"}}

This reply sets a JSESSIONID cookie in the browser so that subsequent calls to the API connect to the authenticated session. If cookies are not enabled or not available in the client technology, you are using then the JSESSIONID may be sent as a URL parameter to subsequent API calls to achieve the same result.

If you now retype the catalogs query:

/api/9/catalogs

You should see a list of catalogs visible to the user you authenticated as.

NOTE: the example above used a plain text password. For production environments it is recommended that you use an encrypted password. This is covered in a later section.

REST API Design

The philosophy behind RESTful APIs is that each object in the application domain should be addressable via a unique URL. For example a clip with the id 1234 would have the URL

/api/9/clips/1234

We refer to this URL as the object’s path and it consists of number of elements:

/api - API prefix

/9 - API version number

/clips - the 'endpoint'

/1234 - the 'selector'

All API URLs start with the ‘api’ prefix, to route the call to the correct handler, and the version number to allow the server to handle clients expecting particular versions of the API.

The next element, the ‘endpoint’, represents the collection of all items of a particular type stored on the server – in this case clips. The ‘selector’ (if present) selects a particular item from that collection. If there is no selector then the URL refers to the whole collection.

HTTP Methods

Up to now the examples have involved entering the URL of an API endpoint into a browser. When this is done the browser sends an HTTP GET request to the endpoint. HTTP GET requests are used to retrieve data from the endpoint, but HTTP provides a number of other methods (or verbs) that are used by the REST API to signify the operation you wish to perform on the endpoint.

GET – retrieve one or more objects from the endpoint

POST – adds an object to the collection represented by the endpoint

PUT – updates a specified object in the endpoint collection.

DELETE – delete a specified object from the endpoint collection

To use these other methods, you will typically need to access the API from code.