API Reference Guide

API Introduction

The Userful REST API enables users to programmatically interact with the video walls and displays to have better control over them. Any programming language that supports HTTP 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.
For the list of REST API commands, see api.userful.com.

API User Authentication

Please ensure that a valid user name and password is required to use Userful REST API. The API POST /session allows you to send a username and password to log in. If the authentication is successful you will get a response from the server with your unique session ID. An example session ID looks like this:
1
JSESSIONID=52B9DEF0-4C86-4D67-ABF3-89243ABC4D86
Copied!
Once the ID is available, send it as a cookie parameter together with every other API command. With Javascript or HTML you don't have to do this, as the browser will manage the cookie for you.

Getting Started with the REST API

Running your first few commands

Ensure that any REST API Client is installed for the purpose of testing. This will aid in quick debugging and testing of REST API commands.
Find the IP address of your server. If you normally access the Control Center with a URL of, for example, http://192.168.120.199/ucc.html, Then you will use http://192.168.120.199 to access the server.
Configure all necessary Zones and Sources, using naming conventions you will remember. For the purpose of this example, we will assume that the names are: zone_1, source_1, and source_2.
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:
1
http://123.168.120.199/api/zones/byname/zone_1/switch?destinationSourceName=source_2
Copied!
Choose PUT method and click "Send".
Play source_2 on zone_1:
1
http://123.168.120.199./api/zones/byname/zone_1/playAssignedSource
Copied!
Choose PUT method and click "Send". This will play source_2 on zone_1.

Communicating with the 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 Python, JavaScript and C#.

Python

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)
1
from httplib import *
2
from urllib import quote
3
import json
4
5
host = "http://localhost:9000"
6
7
def login():
8
conn = HTTPConnection(host)
9
method = "POST"
10
url = "/api/session"
11
body = """
12
{
13
"user" : "user",
14
"password" : "password"
15
}
16
"""
17
conn.request(method, url, body)
18
response = conn.getresponse()
19
status = response.status
20
session_header = None
21
if status == 200:
22
data = response.read()
23
print status, data
24
session = json.loads(data)["session"]
25
session_str = session["name"] + "=" + session["value"]
26
session_header = {"cookie":session_str}
27
print session_header
28
conn.close()
29
return session_header
30
31
def play(session_header, zone_name):
32
conn = HTTPConnection(host)
33
method = "PUT"
34
url = "/api/zones/byname/%s/playAssignedSource" % quote(zone_name)
35
url = quote(url)
36
body = ""
37
conn.request(method, url, body, session_header)
38
print "Playing %s " % zone_name
39
40
if __name__ == '__main__':
41
session_header = login()
42
play(session_header, "Zone-0")
Copied!

JavaScript

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:
1
chromium-browser --disable-web-security --user-data-dir
Copied!
Sending a Broadcast Alert:
1
ROOTURL = 'http://192.168.120.199:9000/api';
2
function startBroadcast(_message, _alertLevel, _duration) {
3
$.ajax({
4
type: 'PUT',
5
url: ROOTURL + '/system/broadcast/start',
6
data: JSON.stringify({
7
message: _message,
8
alertLevel: _alertLevel,
9
lengthMillisec: _duration
10
}),
11
success: function(result, textStatus, jqXHR){
12
alert('Broadcasting now');
13
},
14
error: function(jqXHR, textStatus, errorThrown){
15
alert('Broadcast error: ' + textStatus);
16
}
17
});
18
}
Copied!
Explanation
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
1
http://192.168.120.199:9000/api/system/broadcast/start
Copied!
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
1
startBroadcast("Hello World", "RED_LEVEL", 6000)
Copied!
You have options to handle the cases where the broadcast is successful or not. In this example you will get different message boxes. Most AJAX functions are similar to this example.
Play the profile assigned to the zone
1
function playAssignedProfile(zoneId) {
2
$.ajax({
3
type: 'PUT',
4
url: 'example.com/api/zones/' + zoneId + '/playAssignedProfile'
5
});
6
}
Copied!
This function takes the zone ID and plays it, for example
1
playAssignedProfile('178DA782-E721-11E5-9730-9A79F06E9478');
Copied!
Stop playing a zone
1
function stopZone(zoneId) {
2
$.ajax({
3
type: 'PUT',
4
url: 'example.com/api/zones/' + zoneId + '/stop'
5
});
6
}
Copied!
Switch a zone to another source
1
function switchZone(zoneId) {
2
$.ajax({
3
type: 'PUT',
4
url: 'example.com/api/zones/' + zoneId + '/switch'
5
});
6
}
Copied!
Make a playlist and play it on a zone
1
function playVideoList(zoneId) {
2
$.ajax({
3
type: 'PUT',
4
data: JSON.stringify({
5
"videolist": [
6
"/video/1.mp4",
7
"/video/2.mp4"
8
],
9
"queue": false,
10
"repeat": false,
11
"slideshowInterval": 10
12
}),
13
url: 'example.com/api/zones/' + zoneId + '/playVideoList'
14
});
15
}
Copied!

C#

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.
1
string getSessionId() {
2
using (var httpClient = new HttpClient())
3
{
4
httpClient.BaseAddress = "http://localhost:9000";
5
dynamic loginInfo = new ExpandoObject();
6
loginInfo.user = "user";
7
loginInfo.password = "your password";
8
var auth = JsonConvert.SerializeObject(loginInfo);
9
var buffer = System.Text.Encoding.UTF8.GetBytes(auth);
10
var byteContent = new ByteArrayContent(buffer);
11
var ret = httpClient.PostAsync("/api/session", byteContent);
12
IEnumerable<string> retval;
13
ret.Result.Headers.TryGetValues("Set-Cookie", out retval);
14
if (retval != null)
15
return retval.FirstOrDefault();
16
else
17
return null;
18
}
19
}
Copied!
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.
1
// get the session id first
2
string cookie = getSessionId();
3
object GetSourceList() {
4
using (var httpClient = new HttpClient())
5
httpClient.BaseAddress = "http://localhost:9000";
6
var message = new HttpRequestMessage(HttpMethod.Get, "/api/sources");
7
// add cookie value to the message header
8
message.Headers.Add("cookie", cookie);
9
// send to server
10
var result = httpClient.SendAsync(message);
11
result.Result.EnsureSuccessStatusCode();
12
// get json response
13
var s = result.Result.Content.ReadAsStringAsync().Result;
14
return JsonConvert.DeserializeObject(s);
15
}
Copied!