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/api/info

This should return basic information about the server:

{ "status":"OK",
    "data":{
        "version":"CatDV Web Interface 7.0 …”,
        "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 5.

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.