Appendix C. Administrative API

Table of Contents
1. General considerations
2. List all channels
3. List channels for a server
4. Inspect a single channel
5. Import channel configuration for a server
6. Export channel configuration for a server
7. Run archive configuration commands
8. Get the cluster status
9. Get the server status

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

1. General considerations

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.

Request

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.

Response

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

JSON format

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.

Encoding URI components

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