Skip navigation

Request

Structure of the request HTTP_METHOD /RESOURCE/[IDENTIFIERS]

HTTP_METHOD

HTTP methods which are supported.

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.
}

Authentification and authorization

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

If there is no header or not correct data - the server's answer will contain HTTP status 401 Unauthorized and 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

Fields description

mac                    - MAC address
ls                     - personal account
login                  - login account number
status                 - admin status (1 - on, 0 - off)
online                 - STB status (1 - online, 0 - offline)
additional_services_on - Additive services connection status (for example Videoclub, Karaoke, etc. (1 - on, 0 - off)

Example 1. Data obtain about other 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 only 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 description:

login - authorization login (unique, required);
password - authorization password;
full_name - user's name (the first and the last name or organization name);
account_number - account number;
tariff_plan - tariff plane identifier;
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 status (1 - online, 2 - offline);
ip - IP address of STB;
version - string with firmware versions, portals, etc.;
subscribed - list of optional package identifiers for which there is a subscription;
comment - comment string, available for admin only;
end_date - disabling date (while enable_internal_billing = true) in format "Y-m-d H:i:s";
account_balance - the string containing the balance. For example, "100 UAH.";
last_active - time and date of last activity (playing content).

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 using 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, reboot, reload_portal, update_channels, play_channel, update_image, 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]}  

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.

Fields 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 managment.

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

Supported methods: GET, PUT.

Available fields for updating: sub_ch.

Fields 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 of concrete 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 of concrete 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 description.

id                     - ID of tariff plan
external_id            - ID for external systems
name                   - name
user_default           - default option of tariff plan
packages               - service packet's description

Description of service packages fields.

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           - packet type (periodic or single)
rent_duration          - rent duration (для service_type = single)
optional               - flag (it shows that packet 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.

Fields description.

id                     - ID of service packets
external_id            - ID for external services
name                   - name
type                   - type (video, tv, radio, module)
description            - description
all_services           - flag (it shows that packet contains all services)
service_type           - packet type (periodic or single)
rent_duration          - rent duration (for service_type = single)
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 packets.

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).

Fields description.

mac                    - MAC address
subscribed             - list of optional packets (external_id)
subscribed_id          - list of optional packets (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. Unsubscription on 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. Unsubscription on all optional packages.

> DELETE [API_URL]/account_subscription/1553
< {"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?

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.