This old wiki is now closed for editing. Articles which are still useful and up-to-date will be transfered to the new Wiki shortly.
For the official documentation, please look at the download page.
REST Remote Interface
From mAirListWiki
The REST remote interface allows network access to a running mAirList instance. It was introduced in mAirList 3.1, replacing the SOAP-style network interface. REST is the abbreviation for Representational State Transfer and is a concept for remote access to an application (a.k.a. web service) through the simple HTTP protocol.
The REST interface allows read and write access to mAirList and its data through HTTP GET and POST calls. Most functions return machine-readable data in e.g. XML format which allows external applications to interact with mAirList through this interface.
The interface runs on port 9300 and by default supports password protection through HTTP basic authentication. The operations are grouped into plugins which can be enabled and disabled separately. This allows you to limit the functionality of the network interface to the operations you really need for your application, and thereby limit the security threats inherent in a network-based remote interface.
Contents |
Accessing the REST Server
All operations are invoked by simple HTTP GET or POST calls. See the section Plugin Description below for a list of all available operations.
URLs
The server runs on port 9300 by default, so all URLs start withhttp://<ip>:9300/by default. However, you can change the port number in the configuration, and you can also have multiple REST remotes running simultaneously on different ports. When writing a REST client for mAirList, ensure that you make the port number configurable, just like the IP or host name.
Parameters
Many operations expect parameters as part of the URL or HTTP call. Operations based on HTTP GET will usually use parameters embedded in the URL. POST-based operations usually have parameters in the path that specifies the object the operation is to be performed on (for example the ID of a playlist), and additional form data parameters that specify the parameters of the action (for example the ID of an item to remove from a playlist).
Authentication
The administrator can choose to protect the service by entering a username and password in configuration. In this case, the REST server will use basic HTTP authentication and send a 401 "Authorization required" response if the wrong credentials or no username at all is specified.
Plugin Description
General Status (read only) - GeneralRead
Request ON AIR status
Syntax: GET /status/onair (no parameters)
Returns the current ON AIR status as a single-digit number (1 = on air, 0 = off air).
Command Execution - ExecuteCommand
Execute a Command
Syntax: POST /execute
Executes a fader start command (e.g. PLAYER 1-1 START). The command must be passed as a parameter named command in the POST request.
Encoder Status - Encoder
Request General Encoder Status
Syntax: GET /encoder/summary (no parameters)
Returns a JSON document describing the current encoder status, with the following fields:
- Connections: List of connections with summary description (see below)
- Connected: Current global connection status (0 or 1)
- Listeners: Total number of listeners for all connections
Request Connection Status
Syntax: GET /encoder/connection/<number>/summary
Retrieves the status of a specified single connection. The connection number corresponds to the index in the Connections list of the general encoder status. The server returns a JSON document with the following fields:
- Name: Name/Description of the connection as entered in the configuration
- Enabled: Is the connection enabled? 0 or 1.
- Connected: Is the connection established? 0 or 1.
- Listeners: Number of listeners for this connection.
Request Connection Name
Syntax: GET /encoder/connection/<number>/name
Returns the name/description of a particular encoder connection.
Request Connection Enabled State
Syntax: GET /encoder/connection/<number>/enabled
Returns 1 (connection is enabled) or 0 (connection is disabled).
Request Connection State
Syntax: GET /encoder/connection/<number>/connected
Returns 1 (connection is established) or 0 (connection is not established).
Request Connection Listener Count
Syntax: GET /encoder/connection/<number>/listeners
Returns the number of listeners for this connection.
