Protocol

The HTTP Protocol

The application provides two general HTTP endpoints: /auth and /info. As their names suggest, /auth is used to authenticate with the system and /info provides information about the application's setup needed to communicate with it.

The /auth endpoint

Auth requests

Requesting authentication can be done through sending a POST request to /auth with the following JSON body:

{
    "method": "<Authentication_Method>",
    "credentials": "..."
}

PAM Authentication

By now, PAM is the only authenication mechanism supported. However PAM is very flexible, so that many different auth flows an be implemented using the PAM configuration file for excubitor (/etc/pam.d/excubitor).

The credentials object for authenticating with PAM, looks like the following:

{
    "username": "<Your_Username>",
    "password": "<Your_Password>"
}

Auth response

After authenticating successfully, you'll receive an auth response like the following:

{
    "access_token": "<Access_Token>",
    "refresh_token": "<Refresh_Token>"
}

Refreshing your tokens

The endpoint /auth/refresh can be used to get a new access token. Therefore, you need to authenticate using the refresh token by HTTP bearer authentication. However, this method is discouraged and we have not implemented refreshing a session in the frontend as the sessions usually are not long enough for a need to refresh them.

The WebSocket Protocol

Connecting to WebSocket

Connecting to the WebSocket endpoint happens through the HTTP Upgrade mechanism. Most websocket libraries and tools should handle this automatically.

To authenticate with the websocket endpoint, the connection URL should look like the following:

https://<Your_Base_URL>/ws?token=<Your_Access_Token>

WebSocket Message

A WebSocket Message looks like the following:

{
    "op": "<OP_Code>",
    "target": "<Your_Target>",
    "value": "<Your_Optional_Value>"
}

In requests, the value field is optional and can be used for further specification of a request. The value field is a string and may be of any encoding. However, module creators are strongly encouraged to use an escaped JSON string for encoding. Error values may not be encoded at all. They are just plain strings.

OpCodes

The following OpCodes are available:

• GET: Getting a single value of a target
• SUB: Getting all following values of a target
• UNSUB: Unsubscribing from receiving values of a target
• HIST: Getting the history of a target
• REPLY: Reply to a request (Only the server can send this OpCode)
• ERR: Error (Only the server can send this OpCode)

Note: The delivery of replies for GET and SUB requests is not guaranteed. When a target does not exist, the application will never give you an error! Also, the time between you requesting a resource and delivery varies through the configuration of the application.

HIST Requests

In HIST requests you can specify multiple parameters in the value field:

{
    "after": "<DATE>",
    "until": "<DATE>",
    "max_density": "<Duration>"
}

In the after field you can specify the earliest possible date for a returned measurement, in until you can specify the latest possible date for a returned measurement. The max_density field allows for specifying the least temporal difference between two returned measurements. This allows for reducing the payload size when no fine-grained information is needed.

HIST Reply

A HIST Reply is encoded as an escaped json string within the value field of a websocket reply.

Semantics:

[
    {
        "timestamp": "<Timestamp compliant to RFC 3339>",
        "message": {
            "target": "<Target of the original message>",
            "value": "<Value of the original message>"
        }
    }, ...
]