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.
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.
The response is a JSON array, each element being one available archive (JSON object). Each of these JSON objects has the following fields:
| Field name | Internal data type | JSON data type | Description |
|---|---|---|---|
| key | int | number (must be in integer format) | numeric key identifying the archive (unique) |
| name | string | string | name of the archive (might not be unique) |
| description | string | string | 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.