Viblast Documentation

Viblast Portal REST API

(Draft)

What does Viblast REST API offers an interface to the statistical data collected by Viblast Tracker and Viblast Aggregator. This document gives an overview of the capabilities of the REST API.

To get REST API for the collected by Viblast data, you need to install Viblast Portal, part of the Viblast backend infrastructure.

Mapping of clients, streams and stream qualities

The REST API maps three elements - clients, streams and stream quality.

Viblast Portal supports grouping of streams by client. All streams that are added to the system are associated with a client. Each stream can be associated with a number of qualities to describe adaptive bitrate streams.

Get or Insert Client

To add a client to the system, use Get or Insert Client call. You have to use POST request to the following URL:

POST /portal/tracker-api/clients/

The body of the request should contain the name of the client, e.g. "ACME TV", and a client UUID, e.g. "11111111". Client UUID is used as reference key for integration with external to Viblast Portal systems.

{
    "name": "ACME TV",
    "uuid": "11111111"
}

The response to this request contains the client ID into Viblast Portal:

{
    "id": 1
}

If the client already exists this request returns Viblast Portal client ID.

Get or Insert Stream

Streams are added to Viblast Portal by client using Get or Insert Stream call. To add a stream you have to use POST request to:

POST /portal/tracker-api/streams/

The body of the request should contain client ID, received from Get or Insert Client call and CDN stream URL.

{
    "client": 1,
    "cdn_stream": "http://cdn2.viblast.com/streams/big_buck_bunny/adaptive/975k/stream.m3u8"
}

In response to this request Viblast Portal returns stream ID:

{
    "id": 1
}

If the stream already exists this request returns Viblast Portal stream ID

Get or Insert Stream Quality

When the stream supports adaptive bitrate, stream qualities can be added to the stream using Get or Insert Stream Quality call. To add a stream quality you have to use a POST request to:

POST /portal/tracker-api/stream-qualities/

In the body of the request, you have to specify stream ID and the quality bitrate:

{
    "stream": 1, 
    "bitrate": 975
}

The bitrate is expected as an integer parameter.

In response to this call, Viblast Portal returns stream quality ID.

{
    "id": 1
}

Time Series Data

To get time series statistics for a given stream, we need to specify the following parameters:

time interval - we need to specify start and end of the time interval we are interested in;
metric name - Viblast Aggregator pre-computes reports for different metrics (see below) and we have to choose which metric we are interested in;
client, stream and stream quality - we need to specify which client, stream or stream quality we are interested in;

Reports are pre-computed by Viblast Aggregator with 1min resolution.

Time Interval Specification

To specify time interval for the time series data we are interested in, we need to specify start date time <from> and end date time <until>. The accepted date time format is a UNIX timestamp. For example:

<from>: 1431028976 - corresponds to 2015-05-07T23:02:56
<until>: 1431633776 - corresponds to 2015-05-14T23:02:56

Metric Specification

We also need to specify which metric we want to receive. Viblast Aggregator pre-computes reports for various metrics. Examples of metrics currently available follow. More metrics could be added on request.

Concurrent Number of Viewers

full.count - total number of viewers
webrtc.count - total number of viewers that can be part of the PDN (i.e. users with WebRTC-enabled browsers)

Concurrent Number of Viewers per Browser

browser.chrome.full.count - number of viewers using Google Chrome browser
browser.firefox.full.count - number of viewers using Mozilla Firefox browser
browser.ie.full.count - number of viewers using Microsoft Internet Explorer browser
browser.safari.full.count - number of viewers using Apple Safari browser
browser.opera.full.count - number of viewers using Opera browser

Traffic Data

full.down_total - total download traffic
full.down_cdn - download traffic from CDN
full.down_swarm - download traffic from PDN
full.up_swarm - upload traffic to other peers

Traffic Data for PDN Viewers

webrtc.down_total - total download traffic for WebRTC-enabled viewers
webrtc.down_cdn - download traffic from CDN for WebRTC-enabled viewers
webrtc.down_swarm - download traffic from PDN for WebRTC-enabled viewers
webrtc.up_swarm - upload traffic to other peers for WebRTC-enabled viewers

Client and Streams Specification

The client is specified using <client_id> received from the Get or Insert Client request. We can also specify stream and stream quality using <stream_id> obtained via Get or Insert Stream and <quality_id> obtained via Get or Insert Stream Quality.

Time Series Requests

The time series report for the stream quality of a given client stream is available through the following GET request:

GET /portal/api/stats/time/<from>-<until>/<metric>/clients/<client_id>/streams/<stream_id>/qualities/<quality_id>

where specifies the client, - the stream and - the stream quality.

The time series report for a given stream (aggregating all stream qualities) is available by GET request to the following URL:

GET /portal/api/stats/time/<from>-<until>/<metric>/clients/<client_id>/streams/<stream_id>

The time series report aggregating all streams and qualities for a client is available by GET request to the following URL:

GET /portal/api/stats/time/<from>-<until>/<metric>/clients/<client_id>

Example Usage of the Viblast REST API

Example: Number of concurrent viewers for a particular client

If we want to get the full number of viewers for a given client with client ID 11111111 for the time interval 1431654240 to 1431654840 we need to form the following request:

GET /portal/api/stats/time/1431654240-1431654840/full.count/clients/11111111

The body of the response will contain a JSON list containing pairs of values:

[
    [535.0, 1431654300],
    [531.0, 1431654360],
    [533.0, 1431654420],
    [529.0, 1431654480],
    [527.0, 1431654540],
    [533.0, 1431654600],
    [534.0, 1431654660],
    [535.0, 1431654720],
    [535.0, 1431654780],
    [537.0, 1431654840],
    [null, 1431654900]
]

Each pair contains the value and the timestamp - [535.0, 1431654300]. In our example, the value is the number of viewers 535.0, and the timestamp is 1431654300. If there are no values for a given timestamp (for example, if the timestamp is in the future), null will be returned.

The returned data is with 1min resolution.

Example: Number of concurrent WebRTC viewers for a particular client

To get the number of concurrent WebRTC viewers, we need to form the following request:

GET /portal/api/stats/time/1431654240-1431654840/webrtc.count/clients/11111111

The response is similar to the previous example:

[
    [438.0, 1431654300],
    [435.0, 1431654360],
    [435.0, 1431654420],
    [432.0, 1431654480],
    [428.0, 1431654540],
    [436.0, 1431654600],
    [435.0, 1431654660],
    [436.0, 1431654720],
    [438.0, 1431654780],
    [437.0, 1431654840],
    [null, 1431654900]
]

Example: Download traffic from CDN for a particular client

If we want to get download traffic from the CDN, aggregated for all viewers, we have to form the following request:

GET /portal/api/stats/time/1431654240-1431654840/full.down_cdn/clients/11111111

The response will contain a JSON list containing pairs of values:

[
    [2158622720.0, 1431654300],
    [2359073792.0, 1431654360],
    [2503929856.0, 1431654420],
    [2515304448.0, 1431654480],
    [2211820544.0, 1431654540],
    [2168904704.0, 1431654600],
    [2057329664.0, 1431654660],
    [2403556352.0, 1431654720],
    [2362773504.0, 1431654780],
    [2257200128.0, 1431654840],
    [null, 1431654900]
]

Each pair [2158622720.0, 1431654300] contains traffic value 2158622720.0 and a timestamp 1431654300. The traffic value shows the traffic generated by all peers for the timestamped minute in bytes.

Example: Download Traffic from CDN by WebRTC Viewers for a particular client

The request is similar to the previous example:

GET /portal/api/stats/time/1431654240-1431654840/webrtc.down_cdn/clients/11111111

The response contains the following data:

[
    [1720442880.0, 1431654300],
    [1863022592.0, 1431654360],
    [1974493184.0, 1431654420],
    [2028833792.0, 1431654480],
    [1775206400.0, 1431654540],
    [1710138368.0, 1431654600],
    [1621176320.0, 1431654660],
    [1892342784.0, 1431654720],
    [1875288064.0, 1431654780],
    [1821089792.0, 1431654840],
    [null, 1431654900]
]

Example: Number of concurrent viewers for a particular stream

The request for getting data for a given stream is similar to the previous examples. The main difference is that you need to specify stream ID:

GET /portal/api/stats/time/1431654240-1431654840/webrtc.count/clients/11111111/streams/1950124

The response will contain data for viewers of the specified stream in 1min resolution:

[
    [29.0, 1431654300],
    [30.0, 1431654360],
    [30.0, 1431654420],
    [30.0, 1431654480],
    [30.0, 1431654540],
    [30.0, 1431654600],
    [30.0, 1431654660],
    [30.0, 1431654720],
    [30.0, 1431654780],
    [31.0, 1431654840],
    [null, 1431654900]
]

Example: Download Traffic from CDN for a particular stream generated by WebRTC viewers

The request for getting download traffic generated by the viewers of a stream is similar to the previous examples:

GET /portal/api/stats/time/1431654240-1431654840/webrtc.down_cdn/clients/11111111/streams/1950124

The response will contain a JSON list of timestamped data:

[
    [184758272.0, 1431654300],
    [261952512.0, 1431654360],
    [324497408.0, 1431654420],
    [298819584.0, 1431654480],
    [138602496.0, 1431654540],
    [154801152.0, 1431654600],
    [163495936.0, 1431654660],
    [290296832.0, 1431654720],
    [288438272.0, 1431654780],
    [301142016.0, 1431654840],
    [null, 1431654900]
]

Welcome to Viblast Documentation