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”.