This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

REST

    The REST remote (REST Remote Access) is a built-in HTTP/HTTPS server, through which other software can execute remote control commands and query the status of mAirList. All requests require authentication with a username and password, or a token.

    Configuration

    In the configuration app or Control Panel, go to Remote Control and add an interface of type REST Remote Access (Network category).

    General

    • Server Settings: Select the Mode (HTTP only, HTTPS only, or HTTP and HTTPS), and the HTTP Port (default 9300) and HTTPS Port (default 9301).
    • SSL Certificate Files: For HTTPS, select the Certificate and Key files (PEM format), and an optional Root Certificate.
    • User Management: Select where the user accounts are stored: either in the local configuration (Local configuration (auth.db file)), or in one of the configured mAirListDB databases. Click Manage Users… to add or edit users. When a database is selected, you must first sign in with a database user with administrator level.

    In the user management dialog, you can set up users and groups, and set their passwords. For each user or group, the permissions determine which functions of the REST interface they may access, e.g. Command execution, General status (read-only), Playlist read access, Encoder status, or File Server.

    File Server

    The REST server can also serve static files, e.g. a custom web interface that uses the REST API.

    • Enable File Server: Turns on the file server.
    • URL Prefix: The path under which the files are available, e.g. www.
    • Document Root: The local folder that contains the files.
    • Allow unauthenticated access: If checked, the files can be retrieved without signing in.

    Authentication

    Clients authenticate using HTTP Basic authentication (username and password), or with a token (Authorization: Bearer ... header). Tokens can be obtained through the /auth endpoint.

    Endpoints

    The following endpoints are available. Numbers in the path (e.g. the playlist number) are counted from 0.

    MethodPathDescription
    GET, POST/executeExecute a remote control command, passed as parameter command.
    POST/actionsExecute an action list, passed as request body. Optional parameters: playlist, timeoffset.
    GET/status/onairReturns the current ON AIR status (true or false).
    GET/runtimedata/<name>Returns the value of a runtime data variable.
    GET/logic/<name>Returns the value of an internal logic state.
    GET/playlist/<n>/contentReturns the content of playlist n as JSON.
    GET/playlist/<n>/content.xmlReturns the content of playlist n as XML.
    POST/log/startLog the start of an item, passed as JSON body (item, id, optional region).
    POST/log/stopLog the stop of an item, passed as JSON body (item, id, optional region and duration).
    GET/encoder/summaryReturns the status of the encoder and all connections.
    GET/encoder/connectedReturns the connection state of the encoder.
    GET/encoder/listenersReturns the total number of current listeners.
    GET/encoder/silenceReturns the number of seconds the audio level has been below the silence threshold.
    POST/encoder/streamtitleUpdates the stream title on all encoder connections, passed as parameter title.
    GET/encoder/connection/<n>/summaryReturns the status of an encoder connection.
    GET/encoder/connection/<n>/nameReturns the name of an encoder connection.
    GET/encoder/connection/<n>/enabledReturns whether an encoder connection is enabled.
    GET/encoder/connection/<n>/connectedReturns whether an encoder connection is established.
    GET/encoder/connection/<n>/listenersReturns the number of listeners on an encoder connection.
    GET/streammonitor/summaryReturns the status of the StreamMonitor and all streams.

    Example, using curl:

    curl -u user:password -d "command=PLAYER 1-1 START" http://localhost:9300/execute
    

    Further endpoints can be implemented in a background script with the OnRESTRequest event handler.