Difference between revisions of "Engine Service API"

From Ace Stream Wiki
Jump to: navigation, search
 
(10 intermediate revisions by one other user not shown)
Line 1: Line 1:
== Методы, которые можно использовать при разработке продуктов, предназначенных для премиум-пользователей и/или которые будут распространяться под индивидуальной лицензией ==
+
==Common description==
 +
Engine service API is intended first of all to provide third-party applications with ability to find out, if any Premium options for the engine, with which application works, are activated. Also API provides ability to activate desired option on behalf of the application.
  
Для проверки ключа пользователя, загрузки расширения и получения списка активированных опций используется веб-интерфейс движка, который работает на порту 6878.
+
Engine service API works at port 6878, if any other port is not specified with option <tt>--http-port</tt>.
  
Запросы отсылаются методами HTTP GET либо POST, ответы в формате JSON.
+
API works via HTTP protocol. Requests are sent to the address <tt><nowiki>http://localhost:6878/webui/api/service</nowiki></tt>
  
Файл-расширение можно получить с помощью API реселлера:
+
Responds are in JSON format, as JSON-RPC, but without id.
http://wiki.acestream.org/wiki/index.php/Reseller_API
 
  
Добавили на вики описание метода API для создания ключа пользователя:
+
==API methods==
http://wiki.acestream.org/wiki/index.php/Reseller_API#createUserKey
 
  
 +
Each request to API must have required parameter <tt>method</tt> that contains a name of  the called method.
  
Метод API createUserkey позволяет создавать ключи двух разных типов. Тип ключа задается параметром type:
+
Below you can see a list of all available methods.
  
'''<tt> type=1 </tt>''' - общий ключ, который обеспечит пользователю получения необходимого Премиум-статуса, для работы с любыми приложениями и отключение определенных форматов рекламы  (такой ключ работает на любых устройствах с любыми приложениями)
+
===check_user_key===
 +
Check, if specified user key is downloaded to the engine.
  
'''<tt> type=2 </tt>''' - ключ для индивидуальной лицензии, который будет работать только с указанным приложением.
+
parameters:
 +
* '''user_key''' (''string'') - user key
  
 +
response options:
 +
* '''{"result": "ok", "error": null}''' - specified key is downloaded to the engine
 +
* '''{"result": "not_found", "error": null}''' - specified key is not downloaded to the engine
 +
* '''{"result": null, "error": "error description"}''' - during query processing error was occurred
  
При создании ключа с типом 2 в запросе обязательно должен быть указан параметр <tt> product </tt> (идентификатор продукта, к которому должен быть привязан ключ).
+
request example:
 +
<nowiki>http://localhost:6878/webui/api/service?method=check_user_key&user_key=1179fcb364f83cc30150b3daffd55ae0a6b70fea</nowiki>
  
Идентификатор продукта можно будет узнать на сайте acccounts.acestream.net (пока этот раздел недоступен мы можем выдавать идентификаторы по запросу).
+
response:
 +
<nowiki>{"result": "not_found", "error": null}</nowiki>
  
Чтобы стать реселлером, нужно зарегистрироваться у нас на сайте и зайти по ссылке:
+
===check_product_user_keys===
https://accounts.acestream.net/reseller
+
Check availability of user keys for a specific product.
  
Откроется форма регистрации реселлера, нужно нажать "зарегистрироваться", после этого мы получим письмо про регистрацию нового реселлера и поставим ему статус "подтвержден". После этого по ссылке https://accounts.acestream.net/reseller будут доступны все инструменты для реселлера.
+
parameters:
 +
* '''product_key''' (''string'') - public part of the product key
  
 +
response options:
 +
* '''{"result": "ok", "error": null}''' - at least one key for a specified application was downloaded to the engine
 +
* '''{"result": "not_found", "error": null}''' - there are no keys for a specified application
 +
* '''{"result": null, "error": "error description"}''' - during query processing error was occurred
  
'''Предлагается следующая схема работы''' (п.2 - работает для версии движка 2.2.1-Next и 3.0.0 Beta):
+
request example:
 +
<nowiki>http://localhost:6878/webui/api/service?method=check_product_user_keys&product_key=1111</nowiki>
  
'''1) Проверка ключа пользователя:'''
+
response:
http://127.0.0.1:6878/webui/app/check-user-key?key=<user_
+
<nowiki>{"result": "ok", "error": null}</nowiki>
key>
 
  
Варианты ответов:
+
===load_extension===
 +
Loading extension [[extension string]] into the app engine
  
* если указанный ключ загружен в движок:
+
To load extension string to the engine you have to send POST request to the address <nowiki>http://localhost:6878/webui/api/service?method=load_extension</nowiki>
  {"status": "ok"}
 
  
* если указанный ключ не загружен в движок:
+
In body of the request you have to transfer contents of the extension string.
  {"status": "not_found"}
 
  
* если при обработке запроса возникла ошибка:
+
response options:
  {"error": "error description"}
+
* '''{"result": true, "error": null}''' - extension was successfully loaded to the engine
 +
* '''{"result": null, "error": "error description"}''' - during query processing error was occurred
 +
 
 +
request example:
 +
<nowiki>http://localhost:6878/webui/api/service?method=load_extension</nowiki>
  
'''2) Чтобы загрузить файл расширения в движок, нужно отправить POST запрос на этот адрес:'''
+
response:
http://127.0.0.1:6878/webui/app/load-extension
+
<nowiki>{"result": true}</nowiki>
  
В теле запроса нужно передать содержимое файла расщирения.
+
===get_services===
 +
Get a list of premium options activated on the engine.
  
Варианты ответов:
+
If parameter <tt>product_key</tt> is transferred, list of options available for all applications, as well as options available only for a specified application comes back.
  
- если расширение успешно загружен в движок:
+
If parameter <tt>product_key</tt> is not transferred, only list of options available for all applications comes back.
  {"status": "ok"}
 
  
- если при обработке запроса возникла ошибка:
+
parameters:
  {"error": "error description"}
+
* '''product_key''' (''string'') - optional parameter that transfers public part of the product key.
  
'''3) Получение списка премиум-опций, активированных на движке:'''
+
request example:
http://127.0.0.1:6878/webui/app/services/get
+
<nowiki>http://localhost:6878/webui/api/service?method=get_services&product_key=1111</nowiki>
  
Формат ответа - массив объектов, каждый из которых описывает одну премиум-опцию.
+
Response format - an array of objects, each of which describes a single premium option.
 +
example:
  
Пример:
+
<nowiki>{
 
+
"result":
[
+
[
 
   {
 
   {
  "id": "noAds",
+
    "id": "noAds",
  "name": "No ADs",
+
    "name": "No ADs",
 
     "valid_from": 1376939146,
 
     "valid_from": 1376939146,
 
     "valid_to": 1411671946,
 
     "valid_to": 1411671946,
 
     "trial": false,
 
     "trial": false,
 
 
     "description": "\u041e\u0442\u043a\u043b\
 
     "description": "\u041e\u0442\u043a\u043b\
    u044e\u0447\u0435\u043d\u0438\u0435 \u0440\u0435\u043a\u043b\u0430\u043c\u044b Ace Stream"
+
u044e\u0447\u0435\u043d\u0438\u0435 \u0440\u0435\u043a\u043b\u0430\u043c\u044b Ace Stream"
 
   }
 
   }
  ]
+
],
 +
"error": null
 +
}</nowiki>
 +
 
 +
or
 +
 
 +
<nowiki>{"result": null, "error": "error description"}</nowiki>
 +
 
 +
Fields:
 +
* '''id''' (''string'') - option ID
 +
* '''name''' (''string'') - option name
 +
* '''valid_from''' (''integer'') - date of option activation (unix timestamp)
 +
* '''valid_to''' (''integer'') - date untill which option is active (unix timestamp)
 +
* '''trial''' (''boolean'') - true, if option was activated for free for a trial period
 +
* '''description''' (''string'') - option description
 +
 
 +
===check_user_service===
 +
Check whether the specified option is enabled on the engine.
 +
 
 +
parameters:
 +
* '''id''' (''string'') - option ID
 +
 
 +
request example:
 +
<nowiki>http://localhost:6878/webui/api/service?method=check_user_service&id=noAds</nowiki>
 +
 
 +
Response format - boolean value.
 +
Example (option is not activated):
 +
 
 +
  <nowiki>{
 +
"result": false,
 +
"error": null
 +
}</nowiki>
  
'''Поля:'''
+
or
  
* '''<tt> id (string) </tt>''' - идентификатор опции
+
<nowiki>{"result": null, "error": "error description"}</nowiki>
* '''<tt> name (string) </tt>''' - название опции
 
* '''<tt> valid_from (integer) </tt>''' - дата, с которой опция активна (unix timestamp)
 
* '''<tt> valid_to (integer) </tt>''' - дата, по которую опция активна (unix timestamp)
 
* '''<tt> trial (boolean) </tt>''' - true, если опция активирована бесплатно на тестовый период
 
* '''<tt> description (string) </tt>''' - описание опции
 

Latest revision as of 15:33, 6 September 2017

Common description

Engine service API is intended first of all to provide third-party applications with ability to find out, if any Premium options for the engine, with which application works, are activated. Also API provides ability to activate desired option on behalf of the application.

Engine service API works at port 6878, if any other port is not specified with option --http-port.

API works via HTTP protocol. Requests are sent to the address http://localhost:6878/webui/api/service

Responds are in JSON format, as JSON-RPC, but without id.

API methods

Each request to API must have required parameter method that contains a name of the called method.

Below you can see a list of all available methods.

check_user_key

Check, if specified user key is downloaded to the engine.

parameters:

  • user_key (string) - user key

response options:

  • {"result": "ok", "error": null} - specified key is downloaded to the engine
  • {"result": "not_found", "error": null} - specified key is not downloaded to the engine
  • {"result": null, "error": "error description"} - during query processing error was occurred

request example:

http://localhost:6878/webui/api/service?method=check_user_key&user_key=1179fcb364f83cc30150b3daffd55ae0a6b70fea

response:

{"result": "not_found", "error": null}

check_product_user_keys

Check availability of user keys for a specific product.

parameters:

  • product_key (string) - public part of the product key

response options:

  • {"result": "ok", "error": null} - at least one key for a specified application was downloaded to the engine
  • {"result": "not_found", "error": null} - there are no keys for a specified application
  • {"result": null, "error": "error description"} - during query processing error was occurred

request example:

http://localhost:6878/webui/api/service?method=check_product_user_keys&product_key=1111

response:

{"result": "ok", "error": null}

load_extension

Loading extension extension string into the app engine

To load extension string to the engine you have to send POST request to the address http://localhost:6878/webui/api/service?method=load_extension

In body of the request you have to transfer contents of the extension string.

response options:

  • {"result": true, "error": null} - extension was successfully loaded to the engine
  • {"result": null, "error": "error description"} - during query processing error was occurred

request example:

http://localhost:6878/webui/api/service?method=load_extension

response:

{"result": true}

get_services

Get a list of premium options activated on the engine.

If parameter product_key is transferred, list of options available for all applications, as well as options available only for a specified application comes back.

If parameter product_key is not transferred, only list of options available for all applications comes back.

parameters:

  • product_key (string) - optional parameter that transfers public part of the product key.

request example:

http://localhost:6878/webui/api/service?method=get_services&product_key=1111

Response format - an array of objects, each of which describes a single premium option. example:

{
"result":
[
  {
    "id": "noAds",
    "name": "No ADs",
    "valid_from": 1376939146,
    "valid_to": 1411671946,
    "trial": false,
    "description": "\u041e\u0442\u043a\u043b\
u044e\u0447\u0435\u043d\u0438\u0435 \u0440\u0435\u043a\u043b\u0430\u043c\u044b Ace Stream"
  }
],
"error": null
}

or

{"result": null, "error": "error description"}

Fields:

  • id (string) - option ID
  • name (string) - option name
  • valid_from (integer) - date of option activation (unix timestamp)
  • valid_to (integer) - date untill which option is active (unix timestamp)
  • trial (boolean) - true, if option was activated for free for a trial period
  • description (string) - option description

check_user_service

Check whether the specified option is enabled on the engine.

parameters:

  • id (string) - option ID

request example:

http://localhost:6878/webui/api/service?method=check_user_service&id=noAds

Response format - boolean value. Example (option is not activated):

{
"result": false,
"error": null
}

or

{"result": null, "error": "error description"}