Documentation API
Description of the protocol for interaction of IPTVPORTAL services with external systems
Protocol IPTVPORTAL JSONSQL ver.0.3 (07.07.2013)
The main entities of the system
subscriber – subscriber of iptv television
terminal – a subscriber device for viewing iptv television (stb, pc player)
media – a media resource available for viewing on a subscriber device (TV channel, video on demand, …)
service – media service (timeshift, youtube, megogo …)
package – a package of media resources (channel package, …)
key – conditional access key for the private media resource
playlist – a list of media resources displayed on the subscriber device (channel categorization, video …)
profile – subscriber profile (parental control, …)
pprofile – player profile, allows you to differentiate media resources depending on the type of terminal (pc, stb, smarttv)
sprofile – a system profile that allows you to differentiate media resources depending on the terminal or subscriber
user – system administrator
domain – system settings
Description of the terminal operation algorithm (STB, PC-player,…)
When turned on, the terminal makes an authentication request, the MAC address and the IP address of the terminal (if there is also a registration identifier) are sent as arguments, if successful, the session identifier is returned, in case of an error, the terminal’s behavior is determined by the system settings.
If the terminal is allowed to register (allow_terminal_reg), the terminal sends a registration request.
The number of terminals for one subscriber can be limited at the system level (max_terminal_per_subscriber), as well as at the subscriber level (max_terminal).
The system settings also provide the ability to deregister the terminal (allow_terminal_unreg), which allows the user to independently change equipment.
It is possible to allow an anonymous user in the system (allow_anonymous), while free media resources will be available to the anonymous user (paid <> true).
The authorized terminal gets access to free media resources (paid <> true), as well as paid resources (paid = true), based on the data of the class diagram shown in the figure.
A paid resource can have an expiration date (expired_on).
Control over the validity period can be implemented by choosing the required update period for the conditional access key (update_period).
IPTVPORTAL JSONSQL protocol
A bunch of HTTPS and JSONRPC is used as a transport for the protocol (http://jsonrpc.org/wiki/specification).
Functionally, the protocol implements commands for manipulating data DML of the SQL language, more precisely the PostgreSQL dialect (http://www.postgresql.org/docs/8.4/interactive/index.html)
The main commands SELECT, INSERT, UPDATE, DELETE have been implemented. The command name is specified in the method JSONRPC field
{
“jsonrpc” : “2.0”,
“id” : 1,
“method” : “select” | “insert” | “update” | “delete”, “params” : {…}
}
SELECT – fetch data request.
Command format
{
“distinct” : distinct_clause,
“data” : data_clause,
“from” : from_clause,
“where” : where_clause,
“group_by” : group_by_clause,
“order_by” : order_by_clause,
“limit” : limit_clause,
“offset” : offset_clause
}
Example. A selection of channels sorted by name.
{
“jsonrpc” : “2.0”,
“id” : 1,
“method” : “select”,
“params” : {
“data” : [“id”, “name”, “protocol”,”inet_addr”,”port”],
“from” : “media”,
“where” : {“is”: [“is_tv”, true]},
“order_by” : “name”
}}
Example. A selection of subscribers sorted by login name.
{
“jsonrpc” : “2.0”,
“id” : 2,
“method” : “select”,
“params” : {
“data” : [“id”, “username”, “password”],
“from” : “subscriber”,
“order_by” : “username”
}}
INSERT - adding new data.
Command format
{
“into” : table_clause,
“columns” : columns_clause,
“values” : values_clause,
“returning” : returning_clause
}
Example. Adding packages “movie”, “sports”.
{
“jsonrpc” : “2.0”,
“id” : 3,
“method” : “insert”,
“params” : {
“into” : “package”,
“columns” : [“name”, “paid”],
“values” : [ [“movie”, true], [“sports”, true] ],
“returning” : “id”
}}
Example. Adding “movie”, “sports” packages to a subscriber with an account name “12345”.
{
“jsonrpc” : “2.0”,
“id” : 4,
“method” : “insert”,
“params” : {
“into” : “subscriber_package”,
“columns”: [“subscriber_id”, “package_id”, “enabled”],
“select” : {
“data”: [{“s”: “id”}, {“p”: “id”}, true], “from”: [
{ “table”: “subscriber”, “as”: “s” },
{ “table”: “package”, “as”: “p” }
],
“where”: {
“and”: [
{ “eq”: [{“s”: “username”}, “12345”]},
]
}
},
“in”: [{“p”: “name”}, “movie”, “sports”]
“returning”: “package_id”
}}
UPDATE - updating existing data.
Command format
{
“table” : table_clause,
“set” : set_clause,
“from” : from_clause,
“where” : where_clause,
“returning” : returning_clause
}
Example. Disconnection of the subscriber with the account name “12345”.
{
“jsonrpc” : “2.0”,
“id” : 2,
“method” : “update”,
“params” : {
“table” : “subscriber”,
“set” : {
“disabled”: true
},
“where”: {“eq”: [“username”, “12345”]},
“returning”: “id”
}}
DELETE - deleting existing data.
Command format
{
“from” : from_clause,
“using” : using_clause,
“where” : where_clause,
“returning” : returning_clause
}
Example. Removing subscriber devices with the account name “test”.
{
“jsonrpc” : “2.0”,
“id” : 2,
“method” : “delete”,
“params” : {
“from” : “terminal”,
“where” : {“in”: [“subscriber_id”, {
“select” : {
“data” : “id”,
“from” : “subscriber”,
“where” : {“eq”: [“username”, “test”]}
}
}]},
“returning”: “id”
}}
Example. Removal of subscriber packages with the account name “test”.
{
“jsonrpc” : “2.0”,
“id” : 2,
“method” : “delete”,
“params” : {
“from”: “subscriber_package”,
“where”: {“in”: [“subscriber_id”, {
“select”: {
“data”: “id”,
“from”: “subscriber”,
“where”: {“eq”: [“username”, “test”]}
}
}]},
“returning”: “id”
}}
Functions and Operations
Logical Operations
{“and”: [op1,op2…]} logical multiplication (AND)
{“or”: [op1,op2…]} logical addition (OR)
{“not”: [op1]} logical negation (NOT) Comparison Operations
{“is”: [op1,op2]}
{“is_not”: [op1,op2]}
{“eq”: [op1,op2]}
{“neq”: [op1,op2]}
{“lt”: [op1,op2]}
{“gt”: [op1,op2]}
{“lte”: [op1,op2]}
{“gte”: [op1,op2]}
Math Operations
{“add”: [op1,op2…]} addition
{“sub”: [op1,op2]} subtraction
{“mul”: [op1,op2…]} multiplication
{“div”: [op1,op2]} division
{“mod”: [op1,op2]} modulo division
Match operators
{“like”: [op1,op2…]}
{“ilike”: [op1,op2…]}
Expressions for Subqueries
{“in”}
{“not_in”}
Client authorization:
API address: https://domain.admin.iptvportal.ru/api/jsonsql/
where “domain” is the subdomain allocated to the operator in IPTVPORTAL
To work with the protocol, you need to add the HTTP header: Iptvportal-Authorization: sessionid = sid
where “sid” is the session identifier obtained during authorization
Administrator authorization:
Authorization address: https://domain.admin.iptvportal.ru/api/jsonrpc/
where “domain” is the subdomain allocated to the operator in IPTVPORTAL
Authorization request:
{
“jsonrpc” : “2.0”,
“id” : 1,
“method” : “authorize_user”, “params” : {
“username” : “admin”, “password” : “adminpassword”
}}
In case of positive authorization:
{
“jsonrpc” : “2.0”,
“id” : 1,
“result” : { “session_id” : “sid”
}
In case of error:
{
“jsonrpc” : “2.0”,
“id” : 1,
“error” : { “message” : “…”
}
Database schema:
Examples of scripts: http://ftp.iptvportal.cloud/doc/API/examples/