REST API v1

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 devided by "," without “space”.

Answer

Structure's answer:

{ "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 - server's answer will contain HTTP status 401 Unauthorized and message:

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

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

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

Supported resources

STB

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

Identifier: personal account, MAC adress (one personal account can contains 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 discription

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

> 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 adress (one personal account can contain only one STB)

Supported methods: GET, PUT, DELETE, POST.

Available fields for updating: password, full_name, account_number, tariff_plan, status, stb_mac. Available fields for adding: login, password, full_name, account_number, tariff_plan, status, stb_mac. Required fields: login.

Field discription:

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 - row with firmware versions, portals, etc subscribed - The list of identifiers of the optional packages in which subscribed comment - comment row, available for admin only end_date - disabling date (while enable_internal_billing = true) in format "Y-m-d H:i:s" account_balance - balance row last_active - time and date of last activity

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}

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

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.

Identificator: 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 (TTL 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. Sendung 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 acount number 12345, during this STB should be turned off (status=0) from resources STB, ACCOUNTS and USERS.

> 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 contains more than one STB).

Supported methods: PUT, GET.

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

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

> POST [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.

> POST [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 discription

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 contains more than one STB).

Supported methods: GET, PUT.

Available fields for updating: sub_ch.

Fields discription

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 packets

Identificator: 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 packet's field

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 packets

Identificator: ID of service packet

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

Identificator: account, MAC address (one account can contain more then 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 packets

> 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 packet

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

Example 3. Unsubscription on optional packets

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

Пример 4. Information updating about all subscribed packets

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

Пример 5. Unsubscription on all optional packets

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