Customer Sign In

upLynk

Integration APIs

Overview

upLynk provides a number of application programming interfaces (APIs) to facilitate integration with third party systems. In general, these APIs are intended for backend integration (your application servers connecting to upLynk's application servers) and not frontend integration (your end users connecting to upLynk's application servers).

Calling conventions

This section describes conventions that are common to all upLynk integration APIs unless otherwise noted.

The integration APIs generally follow some RESTful conventions, but with some simplifications for practical purposes to make accessing them more straightforward. In particular, only the GET and POST HTTP methods are used, never PUT or DELETE, and parameters are usually not included in the URLs.

All responses are a JSON object (never a raw value or an array). The object always has an error member whose value is an integer, with 0 used to indicate no errors. When an error does occur, most APIs include an additional msg member with an error message to aid in troubleshooting.

Each API call takes exactly 2 parameters in form-url-encoded format: a digital signature and a message. The message is an encoded JSON object (details below) that has the request-specific members inside it. The response is also a JSON object with various members as needed. The documentation lists common members of response objects, and new members may be added at any time.

All API calls are performed against the host services.uplynk.com via HTTP or HTTPS.

Messages and signatures

Each API call consists of 2 parameters: msg and sig. The msg parameter is a JSON object that has been encoded according to the rules below. The JSON object itself must contain at least _owner (your account GUID, the 32-hex character string displayed in the gears tab in the CMS, in the Account Settings section), and _timestamp (a timestamp of when the message was generated, in seconds UTC).

The sig parameter is a digital signature for the message. The signature is generated using the instructions below and your secret API key, which is available in the CMS in the Playback Tokens section of the Advanced tab (gears icon).

Message encoding

The msg parameter is generated by taking the JSON string representation of the necessary parameters for the API you are calling and compressing it using zlib. It is then base-64 encoded and any whitespace characters are removed. The example Python code demonstrates this process for a fictional API that takes the 'foo' and 'bar' parameters. Note how the '_owner' and '_timestamp' parameters are also included since they are always required.

Message encoding example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import zlib, time, json

params = dict(
    _owner = '** YOUR ACCOUNT GUID HERE **',
    _timestamp = int(time.time()),
    foo = 'some value',
    bar = 15,
)
msg = json.dumps(params)
msg = zlib.compress(msg, 9).encode('base64').strip()

Digital signature

The sig parameter is generated using your secret API key (from the gears tab in the CMS, under the Playback Tokens sub tab) and computing the hmac/sha256 digest of the msg parameter. Continuing the previous example, the code below computes the signature and then sends off the actual request to the fictional integration API. Note how the msg and sig parameters are encoded before calling the server.

Message encoding example
1
2
3
4
5
import hashlib, hmac, urllib, urllib2
sig = hmac.new('** YOUR SECRET API KEY HERE **', msg, hashlib.sha256).hexdigest()

body = urllib.urlencode({'msg':msg, 'sig':sig})
print urllib2.urlopen('http://services.uplynk.com/api2/fake', body).read()

Code samples

The documentation for each integration API includes a sample call and a sample response. For brevity, all sample calls assume the following code has been used to provide a helper function. Substitute your own account GUID and secret key as needed.

Common API code (Python)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import urllib2, urllib, zlib, hmac, hashlib, time, json

ROOT_URL = 'http://services.uplynk.com'
OWNER = 'c56ea4014685bc74c0a375236cc5a735' # CHANGE THIS TO YOUR ACCOUNT GUID
SECRET = 'GESKwbpWxQ/QhHFmhTZLLu3rYeNuK4gYrWwlCLnT' # CHANGE THIS TO YOUR SECRET API KEY

def Call(uri, **msg):
    msg['_owner'] = OWNER
    msg['_timestamp'] = int(time.time())
    msg = json.dumps(msg)
    msg = zlib.compress(msg, 9).encode('base64').strip()
    sig = hmac.new(SECRET, msg, hashlib.sha256).hexdigest()
    body = urllib.urlencode(dict(msg=msg, sig=sig))
    return json.loads(urllib2.urlopen(ROOT_URL + uri, body).read())

print Call('/api2/fake', foo='some value', bar=15)
			
Common API code (PHP)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?php
$ROOT_URL = 'http://services.uplynk.com';
$OWNER = 'c56ea4014685bc74c0a375236cc5a735';
$SECRET = 'GESKwbpWxQ/QhHFmhTZLLu3rYeNuK4gYrWwlCLnT';

function encode_array($args)
{
  if(!is_array($args)) return false;
  $c = 0;
  $out = '';
  foreach($args as $name => $value)
  {
    if($c++ != 0) $out .= '&';
    $out .= urlencode("$name").'=';
    if(is_array($value))
    {
      $out .= urlencode(serialize($value));
    }else{
      $out .= urlencode("$value");
    }
  }
  return $out . "\n";
}

function Call($uri, $msg=array())
{
    global $ROOT_URL, $OWNER, $SECRET;

    $msg['_owner'] = $OWNER;
    $msg['_timestamp'] = time();
    $msg = json_encode($msg);
    $msg = base64_encode(gzcompress($msg,9));
    $sig = hash_hmac('sha256', $msg, $SECRET);
    $sig = trim($sig);
    $body = encode_array(array('msg'=>$msg, 'sig'=>$sig));
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $ROOT_URL . $uri);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
    $result = curl_exec($ch);
    curl_close($ch);
    return $result;
}
			

The Call() helper function takes care of preparing the message body and digital signature, and allows for a simple calling format. Using this helper, the example from the Messages and signatures section could be reduced to:

Shorter calling example of fictional API
Python:
print Call('/api2/fake', foo='some value', bar=15)

PHP:
echo Call('/api2/fake', array('foo'=>'some value', 'bar'=>15));
			

For clarity, all code samples are displayed in Python and PHP, but the APIs can of course be called from any modern programming language - there is nothing language-specific in the upLynk integration APIs.

Available APIs

The integration APIs are organized into the following groups. Please refer to the corresponding page for each group for additional information.

adad-related APIs
assetinformation about assets in your content library
channelinformation about linear channels in your account
cloudslicermanage cloud-based slicer jobs
libraryManage shared libraries.
live eventsmanage live events
ownersmanage API keys and link accounts
slicerinformation about live slicers in your account
subownerscreate and manage restricted-use login credentials for your account
tokenplayback authorization token utilities