====== DHD REST API ======
The DHD REST API comes with Firmware Version 9.1 & Web Apps version 2.0. It is meant to provide easy access to useful functionalities of the console and is designed primarily to write. Reading values is only possible for global labels. This is to prevent polling.
DHD REST API is restricted to an average of one request per second, but can handle bursts of up to 10 requests per second. After such a burst of e.g. 10 requests, you will have to wait 10 seconds before the server accepts any new calls. If you have a Burst of e.g. 5 requests, you will have to wait 5 seconds. During this 'grace period', the server will respond with code ''423 (Locked)''.
**REST API (system)** will be reduced in its feature set, as it would introduce duplicate functions as the new control API.
The following calls are deprecated within firmware version 10.2 and will be removed soon:
* Load Mixer Snapshot
* Save Mixer Snapshot
* Load Channel Snapshot
* Save Mixer Snapshot
* Upload Mixer Snapshot
* Download Mixer Snapshot
* Upload Channel Snapshot
* Download Channel Snapshot
**Note**\\ All examples can vary on different platforms and shell / terminal environtments. Please check for the correct syntax on your environment.
REST API must be enabled in [[tb9:start|Toolbox]], [Device Node] > ''Web Apps'' Tab, REST API checkbox.
===== Labels =====
==== Set Global Label ====
Set a single global label
^Action path |''/action/setgloballabel'' |
^Types possible |''Get, Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |''1'' |Global label ID|
^Name |String |''test'' |New global label value|
^Token |String |''XXX-XXX-XXX'' |User authentication (optional)|
=== Example Request ===
curl -L -X GET 'http://1.2.3.4/action/setgloballabel?ObjectID=1&Name=test'
==== Get Global Label ====
Get a single global label
^Action path |''/action/getgloballabel'' |
^Types possible |''Get, Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |'''' |Global label ID|
^Token |String |''XXX-XXX-XXX'' |User authentication (optional)|
=== Response ===
The response is the label value in plain text.
=== Example Request ===
curl -L -X GET 'http://1.2.3.4/action/getgloballabel?ObjectID=1'
==== Reset Global Label ====
Reset a single global label to Toolbox default.
^Action path |''/action/setgloballabel'' |
^Types possible |''Get, Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |''1'' |Global label ID|
^Name |String |'''' |Has to be empty|
^Token |String |''XXX-XXX-XXX'' |User authentication (optional)|
=== Example Request ===
curl -L -X GET 'http://1.2.3.4/action/setgloballabel?ObjectID=1&Name='
==== Set Channel Label ====
Set a single channel label
^Action path |''/action/setchannellabel'' |
^Types possible |''Get, Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |''1'' |Fader Channel ID|
^Name |String |''test'' |New channel label value|
^Token |String |''XXX-XXX-XXX'' |User authentication (optional)|
=== Example Request ===
curl -L -X GET 'http://1.2.3.4/action/setchannellabel?ObjectID=1&Name=test'
==== Reset Channel Label ====
Reset a single channel label to Toolbox default.
^Action path |''/action/setchannellabel'' |
^Types possible |''Get, Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |''1'' |Fader Channel ID|
^Name |String |'''' |Has to be empty|
^Token |String |''XXX-XXX-XXX'' |User authentication (optional)|
=== Example Request ===
curl -L -X GET 'http://1.2.3.4/action/setchannellabel?ObjectID=1&Name='
===== Pictures =====
==== Upload Picture ====
Upload a picture of file type .png. This function replaces an existing Resource File and can be used for picture elements within TFT views.
**Note**\\ Other file types such as JPG are not supported.
We're using form-data for transmission of the required parameters and file.
^Action path |''/action/updatepic'' |
^Types possible |''Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |''1'' |Resource File ID|
^file |File |''image.png'' |Provide valid PNG here|
^Token |String |''XXX-XXX-XXX'' |User authentication (optional)|
=== Example Request ===
curl -L -X POST 'http://1.2.3.4/action/updatepic' -F 'ObjectID=1' -F 'file=@image.png'
===== User =====
==== Login User ====
Login a specific user on a virtual mixer.
^Action path |''/action/login'' |
^Types possible |''Get, Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |''0'' |Virtual Mixer ID|
^Token |String |''XXX-XXX-XXX'' |User authentication|
=== Example Request ===
curl -L -X GET 'http://1.2.3.4/action/login?Token=XXX-XXX-XXX&ObjectID=0'
==== Logout User ====
Logout a any user on a virtual mixer with a valid user token.
^Action path |''/action/logout'' |
^Types possible |''Get, Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |''0'' |Virtual Mixer ID|
^Token |String |''XXX-XXX-XXX'' |User authentication|
=== Example Request ===
curl -L -X GET 'http://1.2.3.4/action/logout?Token=XXX-XXX-XXX&ObjectID=0'
===== Snapshots =====
==== Load Mixer Snapshot ====
Load a mixer snapshot on the console.
^Action path |''/action/loadmx'' |
^Types possible |''Get, Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |''0'' |Virtual Mixer ID|
^SnapshotID |Int |''1'' |Snapshot ID to load|
^Token |String |''XXX-XXX-XXX'' |User authentication (optional)|
=== Example Request ===
curl -L -X GET 'http://1.2.3.4/action/loadmx?ObjectID=0&SnapshotID=1'
==== Load Channel Snapshot ====
Load a channel snapshot on the console.
^Action path |''/action/loadch'' |
^Types possible |''Get, Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^ObjectID |Int |''0'' |Fader Channel ID|
^SnapshotID |Int |''1'' |Snapshot ID to load|
^Token |String |''XXX-XXX-XXX'' |User authentication (optional)|
=== Example Request ===
curl -L -X GET 'http://1.2.3.4/action/loadch?ObjectID=0&SnapshotID=1'
==== Upload Channel Snapshot ====
Upload a channel snapshot on the console. The channel snapshot can be downloaded using Snapshots App.
^Action path |''/action/uploadchsnap'' |
^Types possible |''Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^SnapshotID |Int |''1'' |Snapshot ID to load|
^file |file |''ChannelSnap_1.sfp'' |Local fader shapshot file|
^Token |String |''XXX-XXX-XXX'' |User authentication (optional)|
=== Example Request ===
curl -L -X POST 'http://1.2.3.4/action/uploadchsnap' -F 'file=@ChannelSnap_1.sfp' -F 'SnapshotID=1'
===== Backup / Restore | Version >10.1 =====
**Note**\\ This feature comes with minimum firmware version 10.1.0
To choose, what to backup or restore, we use tags. The following tags are allowed:
^Tag^Meaning^Applies to^
|ALL|Creates / restores the full backup (no other tags allowed)|All devices|
|FWCONFIG|Contains the device configuration (from Toolbox)|XC3 / XD3 Cores|
|NETWORK|Contains the network config, such as IP addresses, device name, subnet masks etc.|All devices|
|TIMEZONE|Contains timezone and DST settings|All devices|
|TLS|Contains the TLS certificate of the device|All devices|
|SERVICES|Contains the settings done on Manage Services Page|All devices|
|LOG|Contains syslog settings|All devices|
|SNMP|Contains SNMP settings|All devices|
|USERS|Contains the encrypted user database of the device|XC3 / XD3 Cores|
|MXSNAPS|Contains all mixer snapshots of the device|XC3 / XD3 Cores|
|CHSNAPS|Contains all channel and processing snapshots of the device|XC3 / XD3 Cores|
|SNAPZERO|Contains snapshot zero of each virtual mixer|XC3 / XD3 Cores|
|AES67CONFIG|Contains the AES67 configuration of the deivce|AES67 Interfaces and XC3 Cores with license 52-8546|
**Tip**\\ This API feature can also be used to automatically renew TLS certificates.
==== Download Backup ====
Download a backup of all or selected parameters of the device.
**Note**\\ A file of type ''.bin'' will be downloaded. This has the same contents as the manually downloaded ''.tgz'' file from System App.
^Action path |''/action/backup'' |
^Types possible |''Post'', ''Get'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^Token |String |''XXX-XXX-XXX'' |User authentication (required) |
^Tags |String | ''ALL''|Define what to backup (see list above) |
=== Example Request ===
== Creating a full backup: ==
curl -L -X GET 'http://1.2.3.4/action/backup?Token=XXX-XXX-XXX&Tags=ALL'
== Creating a selective backup of SNMP and Network Config: ==
curl -L -X GET 'http://1.2.3.4/action/backup?Token=XXX-XXX-XXX&Tags=NETWORK,SNMP'
==== Restore (Upload and Apply Backup File) ====
Upload and restore a previously downloaded backup of all or selected parameters of the device
We're using form-data for transmission of the required parameters and file.
**Important**\\ Selected data of the device will be overwritten, device may restart in order to apply the backpu, audio will be interrupted.
**Note**\\ File types ''.bin'' and ''.tgz'' are supported.
^Action path |''/action/restore'' |
^Types possible |''Post'' |
=== Params ===
^Key ^Value Type ^Example ^Description ^
^Token |String |''XXX-XXX-XXX'' |User authentication (required) |
^Tags |String | ''ALL''|Define what to backup (see list above) |
=== Example Request ===
== Restore all Backup Data ==
curl -L -X POST 'http://1.2.3.4/action/restore' -F 'file=@Backup.bin' -F 'Tags=ALL' -F 'Token=XXX-XXX-XXX'
== Restore only Network and AES67 Configuration ==
curl -L -X POST 'http://1.2.3.4/action/restore' -F 'file=@Backup.bin' -F 'Tags=NETWORK,AES67CONFIG' -F 'Token=XXX-XXX-XXX'
===== Responses =====
The server will respond with a status 200 and a JSON object. The JSON object contains the received values such as some data required by DHD audio for debugging. If something on your request goes wrong, the JSON object will contain an ''Error'' entry.
If the server doesn't respond with status code 200:
* Status code ''423 (Locked)'': the REST API is locked because of too many requests (more than 10 per minute)
* Status code ''405 (Method Not Allowed)'':
* check if REST API checkbox is enabled within Toolbox [Device Node] > ''Web Apps'' Tab