API Reference Guide

From Userful Support
< Docs
Revision as of 19:49, 15 May 2019 by Kashif (talk | contribs)
Jump to navigationJump to search

Copyright © 2022 Userful Corporation. All rights reserved.
(Updated 2019.05.15)

To return to the main documentation page, Click Here.


Userful REST API enables users to programmatically interact with the video walls and displays to have a better control over them. Any programming language that supports http protocol such as Java, Python, C#, JavaScript etc can be used for communicating via REST API.

You can use a REST API Client for quick debugging and testing of REST API commands.

This document assumes that user is aware of the programming language used for building REST API code and will walk you through the steps and some examples that will help you getting started with Userful REST API.

User Authentication

Please ensure that a valid user name and password is required to use Userful REST API. The API POST /session allows to send user name and password to log in. If the authentication is successful you will get a response from the server with your unique session ID. For example the ID would look like this:


Once ID is available, send it as a cookie parameter together with every other API command. With javascript/html you don't have to do this as the browser will manage the cookie for you.

Getting started with REST API

Running your first few commands using the API

  • Step 1: Ensure that any REST API Client is installed for the purpose of testing.
This will aid in quick debugging and testing REST API commands.
  • Step 2: Find the IP address of your server.
For example: 
  • Step 3: Setup video wall zones and sources and remember their names. For the purpose of this example assume that the names are: zone_1, source_1, and source_2.
  • Step 4: Paste the following command into REST API Client and test it. This will switch zone_1 to play source_2.
  • Assign zone_1 to source_2 
Choose PUT method and click "Send".
  • Play source_2 on zone_1 
Choose PUT method and press "Send". This will play source_2 on zone_1.

Communicating with API

To communicate with API, write a client program in the programming language that you are familiar with. Here are some code samples written in:


In the following example,two API calls are demonstrated by constructing two functions respectively:

  • login -> POST /api/session
(Login to the system with username and password)
  • play -> PUT /api/zones/byname/{zoneName}/playAssignedSource
(Play the assigned source on the zone by given its zone name)
from httplib import *
from urllib import quote
import json

host = "http://localhost:9000"

def login():
    conn = HTTPConnection(host)
    method = "POST"
    url = "/api/session"
    body = """
              "user" : "user",
              "password" : "password"
    conn.request(method, url, body)
    response = conn.getresponse()
    status = response.status
    session_header = None
    if status == 200:
        data = response.read()
        print status, data
        session = json.loads(data)["session"]
        session_str = session["name"] + "=" + session["value"]
        session_header = {"cookie":session_str}
    print session_header
    return session_header

def play(session_header, zone_name):
    conn = HTTPConnection(host)
    method = "PUT"
    url = "/api/zones/byname/%s/playAssignedSource" % quote(zone_name)
    url = quote(url)
    body = ""
    conn.request(method, url, body, session_header)
    print "Playing %s " % zone_name

if __name__ == '__main__':
    session_header = login()
    play(session_header, "Zone-0")


For security, AJAX requests must be made from the same domain. This feature is known as Cross-origin resource sharing. When developing disable it on Google Chrome or Chromium as follows:

chromium-browser --disable-web-security --user-data-dir

Broadcast alert

function startBroadcast(_message, _alertLevel, _duration) {
    type: 'PUT',
    url: ROOTURL + '/system/broadcast/start',
    data: JSON.stringify({
      message: _message,
      alertLevel: _alertLevel,
      lengthMillisec: _duration
    success: function(result, textStatus, jqXHR){
      alert('Broadcasting now');
    error: function(jqXHR, textStatus, errorThrown){
      alert('Broadcast error: ' + textStatus);


This js function will make an AJAX call to the server to broadcast a message on the screen. The url for this rest command is

The http method is PUT

The parameters are: message ("Hello World"), alertLevel ("RED_LEVEL") and duration in milliseconds (6000). The function call will be simple as

startBroadcast("Hello World", "RED_LEVEL", 6000)

You have options to handle the cases the broadcast is successful or not, In this example you will get different message boxes. Most of AJAX functions are similar to this example.

Play the profile assigned to zone

function playAssignedProfile(zoneId) {
    type: 'PUT',
    url: 'example.com/api/zones/' + zoneId + '/playAssignedProfile'   

This function takes the zone ID and plays it, for example


Stop playing a zone

function stopZone(zoneId) {
    type: 'PUT',
    url: 'example.com/api/zones/' + zoneId + '/stop'   

Switch a zone to other source

function switchZone(zoneId) {
    type: 'PUT',
    url: 'example.com/api/zones/' + zoneId + '/switch'   

Make a playlist and play it on a zone

function playVideoList(zoneId) {
    type: 'PUT',
    data: JSON.stringify({   
       "videolist": [
        "queue": false,
        "repeat": false,
        "slideshowInterval": 10
    url: 'example.com/api/zones/' + zoneId + '/playVideoList'   


You may need namespaces such as Newtonsoft.Json for json manipulation, System.Net.Http and System.Net.Sockets for networking.

Get the session ID value

The following code snippet will send user name and password strings to the server and retrieve the session ID from the cookie, in response from the server.

string getSessionId() {
  using (var httpClient = new HttpClient())
      httpClient.BaseAddress = "http://localhost:9000";
      dynamic loginInfo = new ExpandoObject();
      loginInfo.user = "user";
      loginInfo.password = "your password";
      var auth = JsonConvert.SerializeObject(loginInfo);
      var buffer = System.Text.Encoding.UTF8.GetBytes(auth);
      var byteContent = new ByteArrayContent(buffer);
      var ret = httpClient.PostAsync("/api/session", byteContent);
      IEnumerable<string> retval;
      ret.Result.Headers.TryGetValues("Set-Cookie", out retval);
      if (retval != null)
          return retval.FirstOrDefault();
          return null;

Get source information

Use API GET /sources to get the list of sources available on the server. This code snippet will first authenticate with the sever and then send the request to get the source list.

// get the session id first
string cookie = getSessionId();
object GetSourceList() {
  using (var httpClient = new HttpClient())
  httpClient.BaseAddress = "http://localhost:9000";  
  var message = new HttpRequestMessage(HttpMethod.Get, "/api/sources");
  // add cookie value to the message header
  message.Headers.Add("cookie", cookie);
  // send to server
  var result = httpClient.SendAsync(message);
  // get json response
  var s = result.Result.Content.ReadAsStringAsync().Result;  
  return JsonConvert.DeserializeObject(s);  

Please visit this link to watch the video and learn more about Userful REST API.

Related Links