For most requests HTTP GET is used:

 GET ${TVIPAPI_BASE_URL}/tvipapi/json/<command>.json

For some requests HTTP POST is used:

 POST ${TVIPAPI_BASE_URL}/tvipapi/json/<command>.json

tvipapi/json subfolder allows implementing API inside of existing web site (not dedicated domain).

Here: ${TVIPAPI_BASE_URL} is HTTP/HTTPS base URL of Middleware server. For example, http://server.com/iptv/.
<command> is an API command.

All responses have general form:

{
  "method" : "methodname",
  "status" : 0,
  "text" : "Status text",
  "response" :
    {
    }
}

Client should first check that method name equals original requested method.
Then client should check status integer value for error code.
If status==0 || status==200 (no error), client can parse response object for the requested data.
If status>0, error text could be provided.

To simplify “static” server implementations, content requests can response with HTTP error codes, instead of JSON errors.
server_info command should not response with HTTP error codes as it will be treated as protocol error.

All other API requests should respond HTTP/200, even on error. Error code should be provided in “status” field of JSON responce object!

Server information request. This request is peformed by client on protocol initializtion.
If a server fails to provide Server Info data, client will not access any server features.

Request:

GET ${TVIPAPI_BASE_URL}/tvipapi/json/server_info.json

Response:

{
  "method" : "server_info",
  "status" : 0,
  "response" :
    {
      "proto_version": 1,
      "server": "middleware_server",
      "service_provider":"MegaGiga",
      "server_time": 1234567946,
      "remote_addr": "192.168.10.5",
      "tz_offset": 10800,
      "auth":true,
      "channel_list_update_interval":3600,
      "poll": {
          "interval": 300,
          "timeslot": 0.1,
      }, 
      "cas_configs": [
         {
           "id": 1,
           "type": "tvipcas",
           "options" : {
             "key": "value",
           }
         }
      ]
    }
}

If authentication is enabled by server info, client should authenticate on the server. It should provide any tokens/cookies, that it currently has in this request.

Request:

GET ${TVIPAPI_BASE_URL}/tvipapi/json/auth.json

Response:

{
  "method" : "auth",
  "status" : 0,
  "response" :
    {
      "registered" : true,
      "register_type": "login",
      "session_type": "token",
      "token": "AAAAAAAA",
      "header": "Auth-Data",
      "param": "session"
    }
}

Server should not response with HTTP 403, even if auth failed.

Server should always have response block with register_type option.

registered reports current register status of client. If true - client device was already registered on the server; false - device can be registered, if register_type is defined.

register_type defines type of user authentication logic, implemented by the server. Possible values are:
mac - server uses only MAC address of the device to authenticate it. No Login/Password is used.
login - user should provide login and password to register the device.

session_type defines which kind of session information server will provide to client in order to keep it's registered session. Each successful auth request should correctly update session information (i.e. provide the same or different token). Possible values are:
mac - no token is used. Client just sends it's MAC address in *Mac-Address* HTTP header.
token - a simple string token is provided in the token field of the response. Client Should use HTTP Header “Auth-Token” in each content request too keep session.
cookie - client will keep cookies provided in the current response and apply them to any content request.
header - client will keep the value of token and provide it as custom HTTP-header header.
param - client will keep the value of token attribute and will provide it as GET param on each content request.

If authentication was failed, STB should call Register command, providing credentials according to the register_type (see auth command). Also, all session data, that client may have, should be provided to the call.
If register type is mac, client can immidiately call register command after failed auth.
If register type is login, client should display a message to user with login and password fields. Then call register method.

{
  "login": "login_name",
  "password": "passssss"
}

Request:

GET/POST ${TVIPAPI_BASE_URL}/tvipapi/json/register.json

Response:

{
  "method" : "register",
  "status" : 0,
  "response" : {
      "token": "xxxxxxxxxxxxxxxxxx"
 
  }
}

If registration is OK, no additional data is provided. Client can repeat auth command.

User can try to unregister device. Session information should be provided.

Request:

GET ${TVIPAPI_BASE_URL}/tvipapi/json/unregister.json

Response:

{
  "method" : "unregister",
  "status" : 0,
  "response" : null
}

If unregister is OK (or user is not registered), no additional data is provided. Client can repeat auth command.

Get information about registred user.

Request:

GET ${TVIPAPI_BASE_URL}/tvipapi/json/user_info.json

Response:

{
  "method" : "user_info",
  "status" : 0,
  "response" : {  
      "fullname":"Ivan Smith",
      "enabled":true,
      "contract":"13279 от: 23.06.2014"
   }
}

User structure:

The following commands should only be called by client after successfull authentication.

This command loads channel list from the server. Channel list is always loaded full (all channels).

Request:

GET ${TVIPAPI_BASE_URL}/tvipapi/json/channels.json

Response:

{
	"method": "channels",
	"status": 0,
	"response": {
                "channels_version" : 1,
                "channels_hash": "d41d8cd98f00b204e9800998ecf8427e",
                "epg_version": 1,
		"channels": [{
			"id": 1,
			"title": "ОРТ",
			"number": 666,
			"logo": "http://megaprov.ru/images/logos/ort1.png",
			"url": "udp://@1.1.1.1:1234",
			"age_group_id": 1,
 
		        "tshift_proto":"flussonic",
			"tshift_depth": 3586954,
                        "tshift_base_url": "http://2.2.2.2:4321",
			"tshift_cas_config_id": null,
 
                        "media": {
                          "aspect": "4:3",
                        },
 
			"cas_config_id": null
		}],
 
		"groups": [
		  {
			"id": 1,
			"title": "ProPutina",
			"items": [1, 2, 3, 4]
		  }
		],
		"age_groups":[
		   {
		       "id":1,
                       "age":18,
                       "caption":"18+"
 
		   }
		]
	}
}

channels_version defines version or timestamp or current channel list. If this value is the same as on previous request, playlist will be updated on the device.
channels_hash unique hash of available channels, used in short epg
epg_version defines version or timestamp or current EPG data. If this value is the same as on previous request, EPG will be considered the same.

Channel structure:

Age group structure:

Media structure:

TODO: Some MWs support dynamic links. So, real URL should be async requested by the Player at the moment that user changes channel.

EPG is supposed to be segmented as one file per one day per channel. Day is supposed to be an inteval from 00:00 to 23:59:59 UTC time (*not* local time). The *start* time of event is used.

GET ${TVIPAPI_BASE_URL}/tvipapi/json/epg/<channel_id>/YYYY-MM-DD.json

Here, channel_id is supposed to be the id of channel from the playlist.
YYYY-MM-DD is the date of the requested day (like 2015-01-25). Day borders (begin-end) are defined by server's timezone specified by tz_offset in server info.

Response:

{
  "method" : "epg",
  "status" : 0,
  "response" :
     {
        "version": 2,
        "channel_id" : 1,
        "date" : "2015-01-25",
        "events" : [
          {
            "start": 1447285765,
            "end" : 1447256765,
            "title" : "News",
            "description:" "Today's news program.",
            "age_group_id": 1,
          }
        ],
        "age_groups":[
          {
             "id":1,
             "age":18,
             "caption":"18+"
          }
	]
     }
}

Event structure:

GET ${TVIPAPI_BASE_URL}/tvipapi/json/short_epg/<hash>.json

Here, hash is channel hash.

Filter short EPG by channel:

GET ${TVIPAPI_BASE_URL}/tvipapi/json/short_epg/<channel>/epg.json

Here, channel is supposed to be the id of channel from the playlist.

Response:

{
   "method":"short_epg",
   "status":200,
   "text":null,
   "response":{
      "version":"70",
      "channels":[
         {
            "channel_id":3,
            "events":[
               {
                  "start":1463131800,
                  "end":1463134800,
                  "title":"News",
                  "description":"",
                  "age_group_id":1
               },
               {
                  "start":1463134800,
                  "end":1463138100,
                  "title":"Politics",
                  "description":"",
                  "age_group_id":1
               },
               {
                  "start":1463138100,
                  "end":1463143500,
                  "title":"Just another soap",
                  "description":"",
                  "age_group_id":null
               }
            ]
         }
      ],
      "age_groups":[
         {
            "id":1,
            "age":18,
            "caption":"18+"
         }
      ]
   }
}

version - EPG version

channels structure

Client polls server periodically according to poll settings for incoming messages.
Each client uses its own timeslot to poll server for messages. Each day (starting from UTC 00:00) is splitted into poll intervals.
ceil( ( current_unixtime - (floor(current_unixtime / 86400) * 86400) - floor(poll_timeslot * poll_interval) ) / poll_interval ) * poll_interval + (floor(current_unixtime / 86400) * 86400) + floor(poll_timeslot * poll_interval)

Request:

GET/POST ${TVIPAPI_BASE_URL}/tvipapi/json/messages.json

GET is for message polling (receiving). POST is pushing message (sending).\\

POST request example:

{
  "messages": [
    {
      "id": 1,
      "command": "channel_view_stat",
      "args": {
        "channel_id": 1,
        "content_begin": 111111111,
        "content_end": 22222222,
        "session_begin": 111110000,
        "session_end": 222220000
      }
    }
  ]
}

POST server response example:

{
  "method" : "messages",
  "status" : 0,
}

GET server response example:

{
  "method" : "messages",
  "status" : 0,
  "response" :
     {
        "poll": {
          "interval": 300,
          "timeslot": 0.1,
        }, 
        "messages": [
          {
            "id" : 1,
            "command": "command_name",
            "ttl": 1447285765,
            "args": {
              "arg1": "test1",
              "arg2": "test2"
            }
 
          },
 
        ]
     }
}

Supported message types:

Channel view statistics: