Control API

tip

Control API is the recommended way to interface with modern DHD products.

Current status

Control API is still under development. Release is planned later this year.

Still missing, but scheduled for a later release:

• Fixed Processing Controls

General Information

Control API is a modern approach to interact with your DHD devices. It first comes with firmware version 10.3 or higher and is built to be as easy and efficient to use as possible with security in mind.

It is based upon the following core concepts:

• Simplicity
• Security
• Performance
• Scalability
• Reliability
• Human-Understandability
• Open, standardized technologies

Capabilities

This API is designed to replicate the full state of the DHD device's audio and logic system in the shape of a tree. It can be used to query information one time or subscribe to changes. Queries or subscriptions can be done on specific values or nodes within the tree.

Therefore, the API offers the following connectivity:

• REST: Query the Tree or parts of it one time via HTTP/GET or HTTP/POST
• WebSocket: Query values one time or subscribe to changes of specific values

Data Structure & Syntax

We use JSON as a human readable data format.

The API is structured in four main nodes:

{
    "audio": {},
    "control": {},
    "general": {},
    "range": {}
}

Within every node, we have a set of sub-nodes. We call it a path in reference to tree-like structured data. A path can refer to a node or explicit value. The path to get all settings of automix group 1 of virtual mixer 0 would be: /audio/mixers/0/automix/1/ and return for example:

{
 "_active": true,
 "attmax": 12,
 "attpassive": 15,
 "hold": 260,
 "ratio": 1.5,
 "release": 8.5
}

note

Values that begin with _ are read only and can not be changed via the API.

Security

Control API is built with security in mind. Modern web technologies already deliver us the tools we need to secure every aspect of it.

Transport Layer Security

The API can be encrypted using TLS/HTTPS certificates for both the WebSocket or REST API. Certificates are managed using the device's internal mechanisms.

Authentication

Access to the api is managed via DHD Tokens, managed via WebApps user management. Tokens have to be submitted within every request when using the REST API or when opening a new WebSocket.

Logging

Logging is done via the systems standard syslog mechanisms.

Rate limiting

The REST API is hard limited to one request per second (no matter if it is getting or setting values) to avoid polling and possible performance issues. If faster connectivity is required, use WebSocket instead.

Compliance

The whole API documentation is done using OpenAPI (ex Swagger) specification. It can be viewed and downloaded here.

For WebSocket and POST, the shape of the JSON objects is based on JSON RPC specification, even though the API does not 100% comply, as it is a different use case.