Skip navigation

REST API v1

Request

Structure of the request HTTP_METHOD /RESOURCE/[IDENTIFIERS]

HTTP_METHOD

Supported HTTP method Use
GET

data obtaining

PUT   

 updating
POST creating
DELETE deleting

IDENTIFIERS

Identifiers are divided by "," without “space”.

Answer

Response structure:

{
    "status" : "OK" || "ERROR",
    "results" : [],
    "error" : "" // The field contains an error message string.
}

Authentication and authorization

Basic HTTP authentication supported. All requests to the API must contain correct header Authorization when the authentication is on.

If there is no header or not correct data - the server's response will contain HTTP status 401 Unauthorized and following message:

< {"status":"ERROR","results":"","error":"401 Unauthorized request"}

For successful authentication is sufficient to add in every request header to the API:

Authorization: Basic <base64encode("login":"password")>

Supported resources

STB

STB's management - (it is recommended to use ACCOUNTS instead of STB).

Identifier: personal account, MAC address (one personal account can contain more than one STB).

Supported methods: GET, PUT, DELETE, POST.

Available fields for updating: status, additional_services_on, ls.

Available fields for adding: mac, login, password, status, additional_services_on, ls.

Field name Description

mac     

 STB MAC address
ls personal account

login   

 login account number

status 

 admin status (1 - on, 0 - off)
online STB status (1 - online, 0 - offline)
ip STB IP address
version line with versions of firmware, portal, etc.
additional_services_on additive services connection status (for example Video club, Karaoke, etc. (1 - on, 0 - off)
last_active date and time of the last activity (playing content)

reseller_id

 reseller ID. You can allow the display of information about a reseller by adding an option allow_resellers_info_for_api = true
account_balance balance

Example 1. Data obtain about all STBs.

> GET [API_URL]/stb
< {"status":"OK","results":[{"mac":"00:1A:79:00:15:B3","status":0,"additional_services_on":"0","ls":1553,"login":"1553","online":"1"},
{"mac":"00:1A:79:00:39:5E","status":0,"additional_services_on":"1","ls":3,"login":"3","online":"0"}]

Example 2. Data obtain about one STB using identifier.

> GET [API_URL]/stb/1553
< {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","status":1,"additional_services_on":"1","ls":1553,"login":"1553","online":"1"}]}

Example 3. Data obtain about several STBs using identifier.

> GET [API_URL]/stb/1553,3
< {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","status":1,"additional_services_on":"1","ls":1553,"login":"1553","online":"1"},
{"mac":"00:1A:79:00:21:40","status":0,"additional_services_on":"0","ls":3,"login":"3","online":"0"}]}

Example 4. Updating of STB's data using identifier.

> PUT [API_URL]/stb/1553
> status=1&additional_services_on=0
< {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","status":1,"additional_services_on":"0","ls":1553}]}

Example 5. STB deleting using identifier.

> DELETE [API_URL]/stb/1553
< {"status":"OK","results":true}

Example 6. STB adding using login & password (for authentication).

> POST [API_URL]/stb/
> login=test&password=1234
< {"status":"OK","results":{"mac":"","status":1,"additional_services_on":"1","ls":"0","login":"test"}}

Example 7. STB adding without additive services.

> POST [API_URL]/stb/
> mac=00:1A:79:00:39:5E&additional_services_on=0
< {"status":"OK","results":{"mac":"00:1A:79:00:39:5E","status":1,"additional_services_on":"0","ls":"0","login":""}}

ACCOUNTS

User account control (instead of the STB's resource).

Identifier: personal account, MAC address (one personal account can contain more than one STB).

Supported methods: GET, PUT, DELETE, POST.

Available fields for updating: login, password, full_name, account_number, tariff_plan, status, stb_mac, comment, end_date, account_balance.

Available fields for adding: login, password, full_name, account_number, tariff_plan, status, stb_mac, comment, end_date, account_balance.

Required fields: login.

Field name Description

login     

 authorization login (unique, required)
password authorization password
full_name user's name (the first and the last name or organization name)

phone         

 phone number
account_number account number
tariff_plan tariff plane identifier
tariff_expired_date validity of the tariff plan
tariff_instead_expired tariff plan that is assigned to the user after the expiration of tariff_expired_date
status admin status (1 - on, 0 - off)

stb_mac

 MAC address of the STB
stb_sn serial number of the device
stb_type model of the device

online

 STB state (1 - online, 2 - offline)
ip IP address of STB
version string with firmware versions, portals, etc.
subscribed list of optional package identifiers (external_id) for which there is a subscription

subscribed_id

 list of optional packages identifiers(internal_id) for which there is a subscription
comment comment string, available for admin only
account_balance the string containing the balance. For example, "100 UAH."
last_active time and date of last activity (playing content)

reseller_id

 reseller ID, you can allow displaying information about the reseller by adding the option allow_resellers_info_for_api = true

reseller_name

 reseller name

Example 1. User's data requesting.

> GET [API_URL]/accounts/00:1A:79:00:39:5E
< {"status":"OK","results":[{"login":"3210","full_name":"Test","account_number":"123","tariff_plan":"FULL","stb_sn":"123345","stb_mac":"FF:FF:FF:FF:FF:FF","stb_type":"MAG250","status":1,"subscribed":[]}]

Example 2. User's account creating.

> POST [API_URL]/accounts/
> login=3210&password=1234&full_name=Test&account_number=123&tariff_plan=FULL&status=1
< {"status":"OK","results":true}

Example 3. User's account updating.

> PUT [API_URL]/accounts/00:1A:79:00:39:5E
> tariff_plan=STANDART
< {"status":"OK","results":true}

Example 4. User's account deleting.

> DELETE [API_URL]/accounts/00:1A:79:00:39:5E
< {"status":"OK","results":true}

USERS

User account control.

Fields and allowed actions completely correspond to the resource ACCOUNTS, except supported identifiers.

As a result a single object is returned instead of collection of objects.

Identifier: login, MAC address.

Example 1. Data obtain about user.

> GET [API_URL]/users/3210
< {"status":"OK","results":{"login":"3210","full_name":"Test","account_number":"123","tariff_plan":"FULL","stb_sn":"123345","stb_mac":"FF:FF:FF:FF:FF:FF","stb_type":"MAG250","status":1,"subscribed":[]}

STB_MSG

Sending messages to the STB.

Identifier: personal account, MAC address (one personal account can contains more than one STB).

Supported methods: POST.

Available fields for updating: msg (text message must be URL encoded), ttl (message lifetime in seconds).

With successful adding results returned true.

Example 1. STB's data updating by identifier.

> POST [API_URL]/stb_msg/1553
> msg=%D0%BF%D1%80%D0%BE%D0%B2%D0%B5%D1%80%D0%BA%D0%B0%20%D1%81%D0%B2%D1%8F%D0%B7%D0%B8
< {"status":"OK","results":true]}

SEND_EVENT

Sending events to STB.

Identifier: Account number, MAC (one Account number can contain more than one STB).

Supported methods: POST.

Allowed fields for update: event (event name: send_msg, send_msg_with_video, reboot, reload_portal, update_channels, play_channel, play_radio_channel, update_image, show_menu, cut_off), msg (message should contain URL encoded), ttl (message lifetime in seconds), need_reboot (reload flag, just for events send_msg), channel (channel number, just for events play_channel)

After successful adding in results returns true.

Example 1. Sending reboot events to all devices.

> POST [API_URL]/send_event/
> event=reboot
< {"status":"OK","results":true]}

Example 2. Sending play channel №10 events to certain STB.

> POST [API_URL]/send_event/00:1A:79:00:00:00
> event=play_channel&channel=10
< {"status":"OK","results":true]}

Example 3. Sending turn off event to STB with account number 12345, during this STB should be turned off (status=0) through STB, ACCOUNTS and USERS resources.

> POST [API_URL]/send_event/12345
> event=cut_off
< {"status":"OK","results":true]}

Example 4. Sending menu display event on a specific STB. 

> POST [API_URL]/send_event/00:1A:79:00:00:00
> event=show_menu
< {"status":"OK","results":true]}

STB_MODULES

Controlling access to the modules (main menu categories).

Identifier: personal account, MAC address (one personal account can contain more than one STB).

Supported methods: PUT, GET.

Available fields for updating: disabled (sections don't display, it is necessary to reboot), restricted (limited access).

Example 1. Access deny to the vclub karaoke, radio module off.

> PUT [API_URL]/stb_modules/00:1A:79:00:39:5E
> restricted[]=vclub&restricted[]=karaoke&disabled[]=radio
< {"status":"OK","results":{"disabled":["radio"],"restricted":["vclub","karaoke"]}}

Example 2. Turn off all restrictions.

> PUT [API_URL]/stb_modules/00:1A:79:00:39:5E
> restricted[]=&disabled[]=
< {"status":"OK","results":{"disabled":[""],"restricted":[""]}}

ITV

Channel list obtaining.

Identifier: Channel ID.

Supported methods: GET.

Field name Description

id    

 channel ID

name

 channel name
number channel number
base_ch base channel identifier

Example 1. All channel's data obtaining.

> GET [API_URL]/itv
< {"status":"OK","results":[{"id":"37","name":"\u041c-TV \u0423\u043a\u0440\u0430\u0438\u043d\u0430","number":"64"}, ...]

ITV_SUBSCRIPTION

Channel subscription's management.

Identifier: personal account, MAC address (one personal account can contain more than one STB).

Supported methods: GET, PUT.

Available fields for updating: sub_ch.

Field name Description

ls                   

 personal account

mac

 MAC address
sub_ch channel ID list
additional_services_on additive services connection status

Example 1. Data obtaining about subscription of all STBs.

> GET [API_URL]/itv_subscription
< {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","sub_ch":["27"],"ls":1553,"additional_services_on":"0"}, {"mac":"00:1A:79:00:15:B3","sub_ch":["27", "29"],"ls":3,"additional_services_on":"0"}]}

Example 2. Data obtaining about subscription the specific personal account.

> GET [API_URL]/itv_subscription/1553
< {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","sub_ch":["27"],"ls":1553,"additional_services_on":"0"},{"sub_ch":["58"],"mac":"00:1A:79:00:15:B3","ls":"1553","additional_services_on":"0"}]}

Example 3. Data obtaining about subscription the specific STB.

 > GET [API_URL]/itv_subscription/00:1A:79:00:39:5E
< {"status":"OK","results":[{"mac":"00:1A:79:00:39:5E","sub_ch":["27"],"ls":1553,"additional_services_on":"0"}]}

Example 4. Data obtaining about all STBs on the personal account.

> PUT [API_URL]/itv_subscription/1553
> sub_ch[]=27&sub_ch[]=29&additional_services_on=1
< {"status":"OK","results":[{"sub_ch":["27","29"],"mac":"00:1A:79:00:15:B3","ls":"1553","additional_services_on":"1"},{"sub_ch":["27","29"],"mac":"00:1A:79:00:39:5E","ls":"1553","additional_services_on":"1"}]}


TARIFFS

Information about tariff plans and service packages.

Identifier: ID of tariff plan.

Supported methods: GET.

Field name Description

id        

 ID of tariff plan

external_id

 ID for external systems
name name
user_default default option of tariff plan

days_to_expires

 the number of days before the expiration of the tariff plan
packages service packages description

Description of service packages fields.

Field name Description

id        

 ID of service packet

external_id

 ID for external system
name name

type

 type (video, tv, radio, module)

description

 description

all_services 

 flag (it shows that packet contains all services)
service_type package type (periodic or single)
rent_duration rent duration (for service_type = single)

price

 cost

optional

 flag (it shows that package is optional)

Example 1. Getting the data about tariff plans.

> GET [API_URL]/tariffs
< {"status":"OK","results":[{"id":"10","external_id":"","name":"\u0422\u0430\u0440\u0438\u0444 \u041f\u0430\u043a\u0435\u0442 +","user_default":"0","packages":[{"id":"10","external_id":"all_video"...

SERVICES_PACKAGE

Information about service packages.

Identifier: ID of the service package.

Supported methods: GET.

Field name Description

id        

 ID of service packet

external_id

 ID for external system
name name

type

 type (video, tv, radio, module)

description

 description

all_services 

 flag (it shows that packet contains all services)
service_type package type (periodic or single)
rent_duration rent duration (for service_type = single)
price cost

services    

 service list or 'all' (it shows all services of such type)

Example 1. Getting the data about tariff plans.

> GET [API_URL]/services_package
< {"status":"OK","results":[{"id":"10","external_id":"all_video","name":"\u0412\u0441\u0435 \u0432\u0438\u0434\u0435\u043e","type":"video","description":"\u041f\u043e\u043b\u043d\u044b\u0439 \u0434\u043e\u0441\u0442\u0443\u043f \u043a \u0432\u0438\u0434\u0435\u043e\u043a\u043b\u0443\u0431\u0443","all_services":"1","service_type":"periodic","rent_duration":"0","services":"all"},...

ACCOUNT_SUBSCRIPTION

Account management on optional packages.

Identifier: account, MAC address (one account can contain more than one STB).

Supported methods: GET, POST, PUT, DELETE.

Available fields for updating: subscribed, subscribed_id, unsubscribed (for PUT), unsubscribed_id (for PUT).

Field name Description

mac   

 MAC address

subscribed

 list of optional packages (external_id)
subscribed_id list of optional packages (internal_id)

Example 1. Data getting about subscribed optional packages.

> GET [API_URL]/account_subscription/1553
< {"status":"OK","results":[{"mac":"00:1A:79:00:15:B3","subscribed":["tv_6","tv_3"]}]}

Example 2. Subscription on optional package.

> PUT [API_URL]/account_subscription/1553
> subscribed[]=tv_2
< {"status":"OK","results":true}

Example 3. Unsubscribe from optional packages.

> PUT [API_URL]/account_subscription/1553
> unsubscribed[]=tv_2
< {"status":"OK","results":true}

Example 4. Information updating about all subscribed packages.

> POST [API_URL]/account_subscription/1553
> subscribed[]=tv_2&subscribed[]=tv_3
< {"status":"OK","results":true}

Example 5. Unsubscribe from all optional packages.

> DELETE [API_URL]/account_subscription/1553
< {"status":"OK","results":true}

RESELLER

Management of resellers, which is carried out after enabling the option  allow_resellers_info_for_api = true in the config.ini file (custom.ini).

Identifier: reseller ID.

Supported methods: GET, POST, PUT, DELETE.

Available fields for adding: name, max_users, use_ip_ranges.

Available fields for updating: name, max_users, use_ip_ranges.

Required fields: name.

Example 1. Getting data about all resellers.

> GET [API_URL]/reseller
< {"status":"OK","results":[{"id": "1","name": "Example Reseller","created": "2018-10-10 16:25:22","modified": "2019-04-08 10:38:46","max_users": "100","use_ip_ranges": "0"}]}

Example 2. Adding a new reseller to the system.

> POST [API_URL]/reseller
> name=2&max_users=200&use_ip_ranges=0
< {"status": "OK", "results": true}

Example 3. Deleting a reseller by ID.

> DELETE[API_URL]/reseller/2
< {"status": "OK","results": true}
Need Help

Cindy is an expert on the Ministra TV platform and the author of this article.

Was this article helpful?

Yes No

Sorry to hear that.
How can we improve this article?

Send
We use cookies in order to optimise our website, provide you with the best possible user experience and help us promote our products. Please read our Cookie Policy to find out how we use cookies and how you can control cookies.
By using this website or closing this message, you acknowledge our Privacy Policy and agree to our use of cookies as described in our Cookie Policy.