Appendix B. JSON archive access protocol 1.0

Table of Contents
1. Requesting the list of available archives
2. Searching for channels
3. Retrieving samples for a channel

The JSON-based archive access protocol is the protocol that is used by the plugin for Control System Studio’s Data Browser. This protocol may also be used by other clients that want to retrieve data from the archive.

Unless the archive-access port has been changed, the base URL used for all requests concerning the JSON-based archive-access protocol 1.0 is http://myserver.example.com:9812/archive-acess/api/1.0. This base has to be prepended to all URLs that are mentioned in this protocol specification. The host name myserver.example.com is just an example and has to be replaced with the real hostname of a Cassandra PV Archiver server. The port 9812 is the default port used for the archive-access protocol and only has to be changed if the archive access port has been changed in the server’s configuration file.

All requests are made by specifying query parameters in the URL. The request body is always empty. The response is always sent in the JSON format (MIME type application/json) unless there is an error (which is identified by a corresponding HTTP status code). All requests are sent as GET requests.

The Cassandra PV Archiver server supports deflate and gzip compression of the response body if support for compression is indicated by the client. For JSON data, compression can dramatically reduce the amount of data that has to be transferred, so clients should support compression when possible.

1. Requesting the list of available archives

Request

The request URL for retrieving the list of available archives has the following form:

/archive/[?prettyPrint]

If the optional prettyPrint parameter is present, the output is formatted nicely, which can be useful for debugging. Usually, this parameter should be omitted because this will result in a more compact representation, saving bandwidth.

Response

The response is a JSON array, each element being one available archive (JSON object). Each of these JSON objects has the following fields:

Field nameInternal data typeJSON data typeDescription
keyintnumber (must be in integer format) numeric key identifying the archive (unique)
namestringstring name of the archive (might not be unique)
descriptionstringstring description of the archive

Originally, the JSON protocol was not designed for the Cassandra PV Archiver, but as a general protocol for accessing archives. For this reason, it supports servers that provide more than one archive. The Cassandra PV Archiver server only provides a single archive, so simple clients can simply assume that the archive key is always 1. The server still supports retriving the archive information so that it is compatible with clients implementing the protocol completely and thus supporting multiple archives.

Example

Request:

GET /archive-access/api/1.0/archive/?prettyPrint HTTP/1.0

Response:

[ {
  "key" : 1,
  "name" : "Cassandra",
  "description" : "Cassandra PV Archive"
} ]