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/api/info
This should return basic information about the server:
{ "status":"OK", "data":{ "version":"CatDV Web Interface 6.8b1-740 …”, "status":"Web Client 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 - possible values are OK, ERROR or AUTH 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 and port 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 is 3.
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/1/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/1/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/1/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.