====== REST Remote Control ======

The REST remote control interface provides a [[https://en.wikipedia.org/wiki/Representational_state_transfer|RESTful]] API, allowing third-party software to access state information, and perform actions, through HTTP calls.

===== Configuration =====

Open the standalone configuration app, or the Control Panel, go to the //Remote Control// page, and add a new //REST Remote Access// remote control.

{{ :config:remotecontrol:pasted:20160907-084121.png?400 }}

==== General Settings ====

Specify the TCP Port that the HTTP server should listen on. The default port is 9300.

SSL versions SSLv3, TLS v1.0, TLS v1.1, and TLS v1.2 are supported from mAirList 6.0 on.

==== User Management ====

Unless you enable anonymous access, all users must authenticate themselves through HTTP Basic Authentication.

Note that all users have the same permissions (with regard to the enabled plugins, see below). If you want to have multiple users with different permissions, you must run multiple REST remotes on different ports.

==== Plugins ====

Endpoint URLs are provided through plugins, which can be enabled or disabled as required. See the plugin description below for the available URLs.
===== Plugins =====

==== General status (GeneralRead) ====

This plugin provides the following endpoints:

  GET /status/onair
  
Returns the current ON AIR status (1 = ON AIR, 0 = OFF AIR).

  GET /runtimedata/<key>
  
Returns the current value of the runtime data value (set in a script via ''SetRuntimeData(key, value)'').
==== Playlist read access (PlaylistRead) ====

This plugin provides the following endpoints:

  GET /playlist/<index>/content
  
Returns the current content of the playlist with the specified index (where 0 is the first playlist) as XML.
==== Command execution (Execute command) ====

This plugin provides the following endpoints:

  POST /execute
  
Executes a [[reference:remote_control_commands|remote control command]], which must be passed as the ''command'' parameter in the POST body.
==== Encoder status (Encoder) ====

This plugin provides the following endpoints:

  GET /encoder/summary
  
Returns a summary of the status of the encoder and all connections as a JSON document.

  GET /encoder/connected
  
Returns the connection state (1 = connected, 0 = disconnected).

  GET /encoder/listeners
  
Returns the current number of listeners.

  GET /encoder/silence
  
Returns the number of seconds since the audio level of the encoder mixer has reached or exceeded the silence level specified in the configuration.

  GET /encoder/connection/<index>/summary
  
Returns a summary of the specified connection (first connection has index 0) as JSON document,
  
  GET /encoder/connection/<index>/name
  
Returns the name of the connection.
  
  GET /encoder/connection/<index>/enabled
  
Returns 1 if connection is enabled in configuration, 0 otherwise.
  
  GET /encoder/connection/<index>/connected
  
Returns 1 if connection has been established, 0 otherwise (disabled or connection error).
  
  GET /encoder/connection/<index>/listeners
  
Returns the number of listeners on this connection.

===== Scripting =====

In mAirList-Script the following functions/procedures can be used:

* ''function HTTPGet(iURL: string ): string''

* ''procedure HTTPGetAsync(iURL: string )''

* ''function HTTPPost(iURL: string, iData: string): string''

* ''procedure HTTPPostAsync(iURL: string, iData: string)''

A complete call for starting Player 1-1 on the remote machine might look like:

''HTTPPost(<nowiki>'http://user:password@<IP-address>:<port>'</nowiki>, 'command=PLAYER 1-1 START');''