API Relaying inside the ROAD Cluster
Relaying REST Requests
All REST request which only refer to the (common) database will be processed in the same way by any ROAD host in this cluster, so a client can send the request to the host of its choice.
Some requests deal either not (only) with the database or have some other impact, which must be processed on a specific machine.
To make this possible, http relaying is implemented in the ROAD Service. In some cases this is done by an explicit REST parameter "host", in others this is managed by the Service depending on the context.
In general relaying can only be directed to one of the hosts, which are registered in the available hosts list, which is described above.
See below documentation for relaying on different API interfaces:
api/ | GET | POST | PUT | DELETE |
|---|---|---|---|---|
api/versions This API allows to query the current versions of a host's Service and Worker version. See api/programs. |
|
Only GET is supported for this interface. |
Only GET is supported for this interface. |
Only GET is supported for this interface. |
api/devices This API allows to query the currently available audio devices on a machine. See api/devices. |
|
Only GET is supported for this interface. |
Only GET is supported for this interface. |
Only GET is supported for this interface. |
api/jobs This API allows to create and access jobs on a specific machine. See api/jobs. |
Receiving jobs data by a query is done with a GET request, which is not relayed. But requesting a job's log file will be relayed to the responsible host because the log files reside only there. |
By POST a job can be created on another host, where a Worker will be created and started. When a job has been created, the Service sets the data field "ProcessingHost" to its own host name. |
A PUT on a job must always be relayed to the processing host, because its active Worker must get updated. Note updates on finished jobs are not allowed. |
Relaying is of DELETE is a pure database operation, except for active jobs with additional parameter "force". By this active jobs can be terminated before deleting them. Because several active jobs might be distributed over several hosts, implicit relaying is supported only for one. |
api/markers |
GET is not supported for this interface. |
|
|
|
api/filtersettings |
Only POST is supported for this interface. |
|
Only POST is supported for this interface. |
Only POST is supported for this interface. |
api/outputswitch |
Only POST is supported for this interface. |
|
Only POST is supported for this interface. |
Only POST is supported for this interface. |
api/metadata |
Only POST is supported for this interface. |
|
Only POST is supported for this interface. |
Only POST is supported for this interface. |
api/schedules This API allows to create and access schedules, which later control jobs on a specific machine. See api/schedules. |
Receiving schedules data by a query is done with a GET request, which is not relayed. |
Relaying is supported for POST, PUT and DELETE requests by the content of the "WorkerHost" field of the schedule - but only if the REST parameter "resetOccurrences" is set, because otherwise there's only an update to the database to be done. With this parameter a currently running job may be affected as well as new pending jobs. If an existing schedule’s WorkerHost is being changed in a PUT request, the update is processed by the old and the new host by relaying accordingly. | ||
api/rundowns |
GET is not supported for this interface. |
|
|
|
via parameter “host”
no relayJob Relay Rule
The standard delay rule defines the order of applying different relay options, which is as follows:
REST parameter “host”: If this parameter is passed, no other relay rule will be applied, even if the resulting host does not match for the context.
JobId via REST parameter or inside an JSON object in REST body: The host will be addressed, which is the ProcessingHost of the job.
REST parameter “alias”: If this parameter is passed, the host will be addressed, which is the ProcessingHost of the job. In case there is more than one job active with this alias, the oldest one (by CreatedTime) will be selected.
If both rule 2. and 3. apply (although not recommended to pass both an alias and a jobId) their resulting job is verified to be the same. If different, a 400 (Bad Request) will be responded.
Relaying Subscriptions and Notifications
All JobState and live data subscriptions can be relayed by passing a RelayHost parameter. This leads the addressed host to relaying to the other host and routing the notifications in the opposite direction back to the requesting client.
This can be useful if a client has no direct network connection to the target host or might decrease network load because the host-to-host relay connection bundles identical subscriptions and notifications for several clients.