This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

REST API

Configuration

On the General tab, the following settings are available:

HTTP Server

  • Port: The default port number is 17011.
  • Bind IP: Enter an IP adress here to bind to a specific local interface. Default is to listen on all interfaces.
  • Document Root: The root folder for the file hosting feature (see below).

Authentication

The HTTP server supports optional authentication, either through HTTP Basic Auth (username and password), or HTTP Bearer Auth (using a base64-encoded bearer token).

If both username/password and token are set, you can any of these to access the server.

WebSocket

Here you can enter an optional list of filters (as regular expressions) for the WebSocket notifications (see below).

Parameters

The REST API connection does not expose any parameters.

Endpoints

The REST API provides the following HTTP endpoints:

Parameters

The current value of a parameter can be queried with:

GET /parameters/<Connection ID>/<Parameter ID>

e.g.

GET /parameters/dhd-studio1/logic/87

If you set the Accept header to application/json, the value will be encoded as a JSON value (string, number, or boolean). Otherwise it will be sent as a plain string.

If the state of the parameter is currently unknown, you will receive a 503 State Unknown reply.

Parameters can be updated with a request to

GET /update

or

POST /update

It expects two parameters in the GET request (or POST body):

parameter=<Connection ID>/<Parameter ID>
value=<new value>

Values are always encoded as a string and will be typecasted to the correct value type automatically.

WebSockets

The REST API provides a WebSocket endpoint under /ws which can be used to receive incoming parameter updates in realtime.

Notifications are sent as JSON objects of the following form:

{
  p: "<Connection ID>/<Parameter ID>",
  v: "<new value>"
}

In order to keep traffic as low as possible, you can limit the parameters to specific subtrees in the configuration.

Parameters can also be updated through the WebSocket connection by sending back JSON objects of the same form. The v part of the object can also be any other JSON type (not just string) and will be converted automatically.

File Hosting

The REST API server can also act as a regular web server, hosting static HTML and other files.

To enable this feature, copy all content to a folder of your choice, and set it as the Document Root in the configuration.

The files will be served directly under the main / directory of the service. You cannot host any files with names that conflict with the built-in endpoints (/ws, /parameters, etc.).