Client REST API

Table of Contents

• Definition

  • HTTP Status Codes

  • API Access Level

• Specification

  • Token API

    • createtokenbased64

    • createtoken

    • destroytoken

    • inquery_server_httpport

    • query_user_days_left

  • Channel API

    • get_channel_list

    • get_channel_category

    • get_channel_uptime

    • get_channel_no

  • Movie API

    • get_movie_list

    • get_movie_category

    • get_movie_info

    • check_user_ppv

    • charge_user_ppv

    • get_movie_ratings

    • check_user_ratings_password

  • Series API

    • get_series_list

    • get_series_profile

    • get_series_episode

    • get_series_category

    Group API

    • query_group

  • Protection API

    • set_player_mac_address

  • EPG API

    • get_epg_info

    • get_day_epg

• Examples

  • Get channel list (HTML with JS script)

  • Video on demand / Pay per view (C/C++)

  • Create / Destroy Token  (Android Java)

  • HTML5 Player  (HTML)

  • Play VOD  (Android Java)

• Appendix A:  Revision History

Definition

HTTP Status Codes

HTTP Status Codes are defined by RFC7213.

API Access Level

For all authorization users.

Specification

Token API

createtokenbased64

The initial EZserver API is to get the authorization token.

Syntax

• GET /token/createtokenbased64?encrpty=xxxxxxxxxx  HTTP/1.0 \r\n\r\n

Parameters

• encrypt: base64-encoded string of user id and password

Return value

• HTTP response status code : "200 OK" with "token=value".

• If successful, value >=0, else value

-1: parameter error

-2: Wrong User ID or Password

-3: User ID Time Expired

Remarks

• An application needs to get a token from EZserver first, then it uses the token to do the following sequential EZserver APIs.

• This initial EZserver APIs are createtoken with user id and password or createtokenbased64 with base64-encoded string of user id and password.

• The application needs to destroy the token by destroytoken with the token, user id and password.

Example

function encode64(input) { 

var keyStr = "ABCDEFGHIJKLMNOP" + 
"QRSTUVWXYZabcdef" + 
"ghijklmnopqrstuv" + 
"wxyz0123456789+/" + 
"="; 
// input = escape(input); 
var output = ""; 
var chr1, chr2, chr3 = ""; 
var enc1, enc2, enc3, enc4 = ""; 
var i = 0; 

do { 
chr1 = input.charCodeAt(i++); 
chr2 = input.charCodeAt(i++); 
chr3 = input.charCodeAt(i++); 

enc1 = chr1 >> 2; 
enc2 = ((chr1 & 3) << 4) | (chr2 >> 4); 
enc3 = ((chr2 & 15) << 2) | (chr3 >> 6); 
enc4 = chr3 & 63; 

output = output + 
keyStr.charAt(enc1) + 
keyStr.charAt(enc2) + 
keyStr.charAt(enc3) + 
keyStr.charAt(enc4); 
chr1 = chr2 = chr3 = ""; 
enc1 = enc2 = enc3 = enc4 = ""; 
} while (i < input.length); 
return output; 
} 

function login(){

 var cgi_url;

 var encrypt_str;

 var userid_pass;

 g_user_id = document.getElementById("user_id").value;

 g_password = document.getElementById("password").value;

 userid_pass=g_user_id+':'+g_password;

 encrypt_str=encode64(userid_pass);

cgi_url = "/token/createtokenbased64?encrpty="+escape(encrypt_str)+"&flag="+Math.random();

xmlHttp.open("GET", cgi_url, true);

xmlHttp.onreadystatechange = login_return;

xmlHttp.send(null);

}

function login_return() {

  if (xmlHttp.readyState == 4)

  {

    var response = xmlHttp.responseText;

    if (response.search("-1")>0)

    {

       alert("parameter error");

    } else if (response.search("-2")>0)

    {

       alert("Wrong User ID or Password");

    } else if (response.search("-3")>0)

    {

       alert("User ID Time Expired");

    }

    else

    {

               g_token=response.slice(6,response.length-2);

}

}

}

function logout()

{

var cgi_url;

  var confirm_msg="Logout?";

  if (confirm(confirm_msg))

{

     g_token=find_cookie_value("token");

          g_user_id=find_cookie_value("userid");

          g_password=find_cookie_value("password");

     cgi_url = "/token/destroytoken?token="+escape(g_token)+"&flag="+Math.random();

         xmlHttp.open("GET", cgi_url, true);

         xmlHttp.onreadystatechange = login_out_return;

         xmlHttp.send(null);

}

}

function login_out_return() {

  if (xmlHttp.readyState == 4)

  {

    var response = xmlHttp.responseText;

      g_token=0;       

   }

}

createtoken

The initial HTTP API is to get the authorization token.

Syntax

• GET /token/createtoken?userid=xxx&password=xxxx  HTTP/1.0 \r\n\r\n

Parameter

• userid: User ID

• password: User Password

Return value

• HTTP response status code : "200 OK" with "token=value". 

• If successful, value >=0, else value

-1: parameter error

-2: Wrong User ID or Password

-3: User ID Time Expired

Remarks

• An application needs to get a token from EZserver first, then it uses the token to do the following sequential EZserver APIs. 

• This initial EZserver APIs are createtoken with user id and password or createtokenbased64 with base64-encoded string of user id and password.

• The application needs to destroy the token by destroytoken with the token, user id and password.

destroytoken

The final HTTP API is to release the authorization token.

Syntax

• GET /token/destroytoken?token=xxxx  HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• userid: User ID

• password: User Password

Return value

• HTTP response status code : "200 OK" with "token=value". 

• If successful, value >=0, else value

-3: Non-Login User ID

-4: Mismatch token for login user id

Remarks

• An application needs to get a token from EZserver first, then it uses the token to do the following sequential EZserver APIs.

• This initial EZserver APIs are createtoken with user id and password or createtokenbased64 with base64-encoded string of user id and password.

• The application needs to destroy the token by destroytoken with the token, user id and password.

inquery_server_httpport

Get Streaming Port.

Syntax

• GET /server/inquery_server_httpport?token=xxxx  HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

Return value

• HTTP response status code : "200 OK" with "httpport=value". 

query_user_days_left

Get user left days.

Syntax

• GET /server/query_user_days_left?token=xxxx  HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

Return value

• HTTP response status code : "200 OK" with "daysleft=value". 

Channel API

get_channel_list

Get channel information of all channels.

Syntax

• GET /server/get_channel_list?token=xxx HTTP/1.0 \r\n\r\n

• GET /server/get_channel_list?token=xxx&type=m3u HTTP/1.0 \r\n\r\n

• GET /server/get_channel_list?token=xxx&category=xxx  HTTP/1.0 \r\n\r\n

• GET /server/get_channel_list?token=xxx&mine=x  HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• type: m3u or hls to get m3u list of main server and all balancers.

• category: Channel category.

• mine: mine=1 : only return channels owned by the authenticated user, mine=0 : return all channels.

Return value

• without type=m3u option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "CH=xx\r\nname=xxx\r\nsrc=xxx\r\nicon=xxx\r\ncategory=xxx\r\ntype=xxx\r\nstatus=xxx\r\n" for each channel, else return HTTP response status code : "404 Not Found"

  •  Content meaning: 

    • CH: Channel no

    • name: Channel name

    • src: Source link header

    • icon: Channel icon path

    • category: Channel category

    • type: live, delay,dvr, hls, inactive

    • status: On/OFF/Connecting/FWD,

• with type=m3u option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and M3U List, else return HTTP response status code : "404 Not Found"

get_channel_category

Get categories of all channels.

Syntax

• GET /server/get_channel_category?token=xxx HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

Return value

• If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "category=xx\r\ncategory=xxx\r\ncategory=xxx\r\n" for Channel Category, else return HTTP response status code : "404 Not Found"

•  Content meaning: 

  • category: Channel category

Remarks

• For example, CH1 category is "Sport", CH2 category is "Sport",  CH3 category is "Kids" and CH4 category is "Action", the response is "category=Sport\r\ncategory=Kids\r\ncategory=Action".

get_channel_uptime

Get channel uptime.

Syntax

• GET /server/get_channel_uptime?token=xxx HTTP/1.0 \r\n\r\n

• GET /server/get_channel_uptime?token=xxx&ch_no=xxx HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• ch_no: channel no

Return value

• with ch_no option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "UptimeSec=xxx\r\nUptime=x days xx:xx:xx\r\n" for the channel.

• without ch_no option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "UptimeSec=xxx\r\nUptime=x days xx:xx:xx\r\n" for all channels

• UptimeSec: its unit is by second.

get_channel_no

Get channel no.

Syntax

• GET /server/get_channel_no?token=xxx HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

Return value

• If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "chno=xxx\r\n"

Movie API

get_movie_list

Get movie names of a movie category

Syntax

• GET /server/get_movie_list?token=xxx&category=xxx HTTP/1.0 \r\n\r\n

• GET /server/get_movie_list?token=xxx&category=xxx&subtitle_type=xxxx HTTP/1.0 \r\n\r\n

• GET /server/get_movie_list?token=xxx type=m3u HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• category: Movie category.

• subtitle_type: Movie Subtitle (vtt).

Return value

• without type=m3u option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "name=xxx\r\nimg=xxx\r\ncategory=xxx\r\ntype=xxx\r\nstatus=xxx\r\n" for each movie, else return HTTP response status code : "404 Not Found"

  •  Content meaning: 

    • name: Movie Name

    • subtilte_path: Subtitle file path (option for subtitle_type)

    • img: Movie icon path

    • category: Movie category

    • type: Movie type

      • 7: MP4

      • 8: TS

      • 9: FLV

      • 10: AVI

    • status: movie status (0/1/FWD)

• with type=m3u option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and M3U List, else return HTTP response status code : "404 Not Found"

get_movie_category

Get categories of all movies

Syntax

• GET /server/get_movie_category?token=xxx HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

Return value

• If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "category=xx\r\ncategory=xxx\r\ncategory=xxx\r\n" 

for Movie Category, else return HTTP response status code : "404 Not Found"

•  Content meaning: 

  • category: Movie category 

Remarks

• For example, Movie 1 category is "Sport", Movie 2 category is "Sport",  Movie 3 category is "Kids" and Movie 4 category is "Action", the response is "category=Sport\r\ncategory=Kids\r\ncategory=Action".

get_movie_info

Get movie more information

Syntax

• GET /server/get_movie_info?token=xxx&&movie_name=xxx  HTTP/1.0\r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• movie_name: Movie Name.

Return value

• If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "description=xxx\r\nrentpoint=xxx\r\nbuypoint=xxx\r\nratingflag=xx\r\nquality=xx\r\nrentperiod=xx\r\n\r\n", 

else return HTTP response status code : "404 Not Found".

• Content meaning: 

  • description: Movie description

  • rentpoint: Rent Point

  • buypoint: Buy Point.

  • ratingflag: 0/1. 1: needs rating password to access the movie..

  • quality: Mobile/SD/HD

  • rentperiod: Rent Period by hours.

Series API

get_series_list

Get all series' brief information

Syntax

• GET /server/get_series_list?token=xxx&category=xxx  HTTP/1.0 \r\n\r\n

Parameter  

• token: the token returned by createtoken or createtokenbased64

• category: category name. if category= to get all categories's series

Return value

• without type option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "series=%s\r\nimg=%s\r\ncategory=%s\r\nseason_no=%d\r\nepisode=%d\r\nreleased_date=%s\r\ndescription=%s\r\n" for each series, else return HTTP response status code : "404 Not Found"

  •  Content meaning: 

    • series: Series Name

    • img: Series icon path

    • category: Series Category

    • season_no: Total season no.

    • episode: Total Episode no.

    • released_date: Released Date.

    • description: Series Description.

• with type option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and M3U List, else return HTTP response status code : "404 Not Found"

get_series_profile

Get a series full information

Syntax

• GET /server/get_series_profile?token=xxx&name=xxx HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• name: Series Name.

Return value

• If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "series=%s\r\nimg=%s\r\ncategory=%s\r\nrating=%s\r\ndescription=%s\r\nseason_no=%d\r\nreleased_date=%s\r\n" for the series, else return HTTP response status code : "404 Not Found"

  •  Content meaning: 

    • series: Series Name

    • img: Series icon path

    • category: Series Category

    • rating: Rating Level.

    • season_no: Total season no.

    • description: Series Description.

    • released_date: Released Date.

get_series_episode

Get all episode names of a series season.

Syntax

• GET /server/get_series_episode?token=xxx&name=xxx&index=xxx HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• name: Series Name.

• index: season number. index=0 means all seasons.

Return value

• without type option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "xxx\r\nxxx\r\nxx\r\nxxx\r\n" for the series season, else return HTTP response status code : "404 Not Found"

  •  Content meaning: 

    • xxx: Episode Name (Movie Name in Movie Panel)

• with type option

  • If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and M3U List, else return HTTP response status code : "404 Not Found"

get_series_category

Get categories of all series

Syntax

• GET /server/get_series_category?token=xxx HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

Return value

• If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "category=xx\r\ncategory=xxx\r\ncategory=xxx\r\n" 

for Series Category, else return HTTP response status code : "404 Not Found"

•  Content meaning: 

  • category: Series category 

Remarks

• For example, Series 1 category is "Sport", Series 2 category is "Sport",  Series 3 category is "Kids" and Series 4 category is "Action", the response is "category=Sport\r\ncategory=Kids\r\ncategory=Action".

check_user_ppv

Check if  the user can watch the specified movie.

Syntax

• GET /server/check_user_ppv?token=xxx&&movie_name=xxx&movie_tran_type=xxx  HTTP/1.0\r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• movie_name: Movie Name

• movie_tran_type: value="rent" or "buy"

Return value

• If successful, HTTP response status code : "200 OK" with "1" or "2", else HTTP response status code : "200 OK" with "0". 

• Return value :

  • "1" : The movie is in the available movie list, the player can play the video directly.

  • "2" : The player needs to call API : charge_user_ppv to pay the fee.

charge_user_ppv

Pay the fee to watch the specified movie.

Syntax

• GET /server/charge_user_ppv?token=xxx&&movie_name=xxx&movie_tran_type=xxx  HTTP/1.0\r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• movie_name: Movie Name

• movie_tran_type: value="rent" or "buy"

Return value

• If successful, HTTP response status code : "200 OK" with "1" or "2", else HTTP response status code : "200 OK" with "0". 

• Return value :

  • "1" : The movie is charged in the available movie list, the player can play the video.

  • "2" : The user mode is free mode, , the player can play the video.

get_movie_ratings

Get movie rating flag

Syntax

• GET /server/get_movie_ratings?token=xxx&&movie_no=xxx  HTTP/1.0\r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• movie_no: Movie no.

Return value

• If successful, HTTP response status code : "200 OK" with "1", else HTTP response status code : "200 OK" with "0". 

check_user_ratings_password

Check the rating password of a user

Syntax

• GET /server/check_user_ratings_password?token=xxx&encrpty=xxxxxxxxxx  HTTP/1.0\r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• encrpty:  base64-encoded string of user id and rating password   .

Return value

• If successful, HTTP response status code : "200 OK" with "1", else HTTP response status code : "200 OK" with "0". 

Group API

query_group

Get all group information

Syntax

• GET /server/query_group?token=xxx HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

Return value

• If successful, return HTTP response status code : "200 OK" with Content-Length: xxxx and 

"No=xx\r\nname=xxx\r\nconnection=xxx\r\nsrc=xxx\r\n

mc_src=all=x,ccc=x,ccc=x,ccc=x\r\n" for each group, else return HTTP response status code : "404 Not Found"

• Content meaning: 

  • No: Group No

  • name: Group Name

  • connection: Define the max concurrent connection for a user in the group

  • src: Allowed Channels

    • Define allowed Channel Categories for the group. The keyword "all" is for all Channel Categories.   .

    • Ex. Actions=1,Kids=0,Sprts=1 means the group users can watch all Channels in Actions and Sports Categories.

    • Ex. all means the group users can watch all channels

  • mc_src: Allowed Movie Categories

    • Define allowed Movie Categories for the group. The keyword "all" is for all Movie Categories.  

    • Ex. Actions=1,Kids=0,Sprts=1 means the group users can watch all movies in Actions and Sports Categories.

    • Ex. all means the group users can watch all Movie Categories.

Protection API

set_player_mac_address

Set the MAC Address of a player

Syntax

• GET /server/set_player_mac_address?token=xxx&macid=xxxxxxxxxxxx HTTP/1.0 \r\n\r\n

Parameter

• token: the token returned by createtoken or createtokenbased64

• macid: the MAC Address of a player, its format is aabbccddeeff (value is between 000000000000 and ffffffffffff)

Return value

• If successful, HTTP response status code : "200 OK" with "1", else HTTP response status code : "200 OK" with "0".

EPG API

get_epg_info

Get Channel EPG information by channel no or channel name.

Syntax

• GET/server/get_epg_info?token=xxx&ch_no=xxx&from_year=YYYY&from_month=MM&to_month=MM HTTP/1.0 \r\n\r\n (get single channel from main server)

• GET/server/get_epg_info?token=xxx&ch_name=xxx&from_year=YYYY&from_month=MM&to_month=MM HTTP/1.0 \r\n\r\n (get single channel from main and balancer epg)

• GET/server/get_epg_info?token=xxx HTTP/1.0 \r\n\r\n (get all channels from main server)

Parameter

• token: the token returned by createtoken or createtokenbased64

• ch_no: channel no

• from_year: year

• from_month: from month

• to_month: to month

Return value

• If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "starttime=YYYY/MM/DD hh:mm:rr\r\nstoptime=YYYY/MM/DD hh:mm:rr\r\ntitle=xxxx\r\ndescription=xxxx\r\nicon=xxxx\r\nrec=x\r\n" for each channel, else return HTTP response status code : "404 Not Found"

•  Content meaning: 

  • starttime: Program Start Time

  • stoptime: Program Stop Time

  • title: Program Name

  • description: Program Detail

  • icon: Icon path: file://xxxx/xxxxx/x.jpg

  • rec: 0/1: OFF/ON for record live channel

get_day_epg

Get Channel EPG information by channel name and interval.

Syntax

• GET/server/get_day_epg?token=xxx&ch_name=xxx&delta=xx HTTP/1.0 \r\n\r\n (get single channel)

Parameter

• token: the token returned by createtoken or createtokenbased64

• ch_name: channel name

• delta: the interval from current day.

  • ex. Current date is 3/10/2020, then 3/9/2020 epg, then delta=-1, 3/12/2020 epg, then delta=2

Return value

• If successful, HTTP response status code : "200 OK" with Content-Length: xxxx and "starttime=YYYY/MM/DD hh:mm:rr\r\nstoptime=YYYY/MM/DD hh:mm:rr\r\ntitle=xxxx\r\ndescription=xxxx\r\nicon=xxxx\r\nrec=x\r\n" for each channel, else return HTTP response status code : "404 Not Found"

•  Content meaning: 

  • starttime: Program Start Time

  • stoptime: Program Stop Time

  • title: Program Name

  • description: Program Detail

  • icon: Icon path: file://xxxx/xxxxx/x.jpg

  • rec: 0/1: OFF/ON for record live channel

Appendix A:  Revision History