The JSON-based administrative web-service API can be used to monitor and configure the Cassandra PV Archiver server. It offers most of the functions available through the administrative user interface, but is designed to be used by other software (e.g. scripts used for automating the configuration management).
The base URL used for all requests concerning this API is:
http://<server>:<port>/admin/api/<version number>
In this URL <server> is the hostname or
IP address of the archive server,
<port> is the TCP port number of the
administrative interface, and
<version number> is the protocol
version.
At the moment, the only protocol version supported by the server is 1.0.
This base has to be prepended to all URLs that are mentioned in this
protocol specification.
If not configured explicitly in the server configuration, the
administrative interface is made available on port 4812.
The API uses JSON for both request and response bodies.
Requests only reading data typically use the GET
method and have an empty request body.
If there are any parameters, they are passed as part of the URL (in the
path or query string).
When passing parameters as part of the path (not the query string), they
have to be encoded in a non-standard way (see
the section called “Encoding URI components” for details).
Read requests do not require authentication.
Requests making modification typically use the POST
method (unless specified differently).
Such requests typically expect parameters in the request’s body.
For some requests however, some of the parameters might still have to
be specified as part of the URL.
Requests making modifications must be accompanied by an
Authorization HTTP header for HTTP basic
authentication.
Invalid credentials result may result in a response with status 403
(forbidden), even if the requested resource does actually not require
authentication.
For this reason, requests to resources not requiring authentication
should rather be made without an Authorization
header than a header containing invalid credentials.
Invalid request parameters (e.g. a request body that does not adhere to the format specified for the respective function) may result in a response with status 400 (bad request).
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).
The request body (if present) also has to be sent in the JSON format
(MIME type application/json).
Unless specified differently, numbers are always serialized as JSON strings for three reasons: First, JSON numbers cannot be used as keys in maps (attribute names in JSON objects). Second, certain special numbers (e.g. positive and negative infinity) cannot be specified as JSON numbers. Third, many JSON parsers convert all numbers to 64-bit floating point values, resulting in precision loss for large integers.
As a general rule, when the member of a JSON object may have a value
of null, it may also be missing.
A missing member must always be interpreted in the same way as the
respective member having a null value.
Parameters that are passed as part of the query string use regular URI encoding (as specified by RFC 3986). Parameters that are passed as part of the path use a slightly different encoding that is specified in this section.
In order to encode a parameter value, it is first serialized as UTF-8. In the resulting byte sequence, each byte that does not represent one of the ASCII characters “A” to “Z”, “a” to “z”, “0” to “9”, “-” (minus), or “_” (underscore) is escaped by a three byte sequence in the form “~” (tilde), hex digit, hex digit. The two hex digits are the escaped byte’s value in hexadecimal representation. The hex digits “A” to “F” should be represented in upper case.
For example, the string “some test” is encoded as “some~20test”. The string “allowed_characters_only” stays the same. The string “a/b” is encoded as “a~2Fb”. The string “süper” is encoded as “s~C3~BCper”.