Difference between revisions of "Engine Service API"

From Ace Stream Wiki
Jump to: navigation, search
(Новая страница: «== Методы, которые можно использовать при разработке продуктов, предназначенных для преми…»)
 
 
(13 intermediate revisions by 2 users 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
 
  
Метод API createUserkey позволяет создавать ключи двух разных типов. Тип ключа задается параметром type:
+
Each request to API must have required parameter <tt>method</tt> that contains a name of  the called method.
  
<tt> type=1 </tt> - общий ключ, который обеспечит пользователю получения необходимого Премиум-статуса, для работы с любыми приложениями и отключение определенных форматов рекламы  (такой ключ работает на любых устройствах с любыми приложениями)
+
Below you can see a list of all available methods.
  
<tt> type=2 </tt> - ключ для индивидуальной лицензии, который будет работать только с указанным приложением.
+
===check_user_key===
 +
Check, if specified user key is downloaded to the engine.
  
 +
parameters:
 +
* '''user_key''' (''string'') - user key
  
При создании ключа с типом 2 в запросе обязательно должен быть указан параметр <tt> product </tt> (идентификатор продукта, к которому должен быть привязан ключ).
+
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
  
Идентификатор продукта можно будет узнать на сайте acccounts.acestream.net (пока этот раздел недоступен мы можем выдавать идентификаторы по запросу).
+
request example:
 +
<nowiki>http://localhost:6878/webui/api/service?method=check_user_key&user_key=1179fcb364f83cc30150b3daffd55ae0a6b70fea</nowiki>
  
Чтобы стать реселлером, нужно зарегистрироваться у нас на сайте и зайти по ссылке:
+
response:
https://accounts.acestream.net/reseller
+
<nowiki>{"result": "not_found", "error": null}</nowiki>
  
Откроется форма регистрации реселлера, нужно нажать "зарегистрироваться", после этого мы получим письмо про регистрацию нового реселлера и поставим ему статус "подтвержден". После этого по ссылке https://accounts.acestream.net/reseller будут доступны все инструменты для реселлера.
+
===check_product_user_keys===
 +
Check availability of user keys for a specific product.
  
 +
parameters:
 +
* '''product_key''' (''string'') - public part of the product key
  
'''Предлагается следующая схема работы''' (п.2 - работает для версии движка 2.2.1-Next и 3.0.0 Beta):
+
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
  
1) Проверка ключа пользователя:
+
request example:
http://127.0.0.1:6878/webui/app/check-user-key?key=<user_
+
<nowiki>http://localhost:6878/webui/api/service?method=check_product_user_keys&product_key=1111</nowiki>
key>
 
  
Варианты ответов:
+
response:
 +
<nowiki>{"result": "ok", "error": null}</nowiki>
  
- если указанный ключ загружен в движок:
+
===load_extension===
  {"status": "ok"}
+
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": "not_found"}
 
  
- если при обработке запроса возникла ошибка:
+
In body of the request you have to transfer contents of the extension string.
  {"error": "error description"}
 
  
2) чтобы загрузить файл расширения в движок, нужно отправить POST запрос на этот адрес:
+
response options:
http://127.0.0.1:6878/webui/app/load-extension
+
* '''{"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>
  
В теле запроса нужно передать содержимое файла расщирения.
+
response:
 +
<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.
  {"status": "ok"}
 
  
- если при обработке запроса возникла ошибка:
+
If parameter <tt>product_key</tt> is not transferred, only list of options available for all applications comes back.
  {"error": "error description"}
 
  
3) получение списка премиум-опций, активированных на движке:
+
parameters:
http://127.0.0.1:6878/webui/app/services/get
+
* '''product_key''' (''string'') - optional parameter that transfers public part of the product key.
  
Формат ответа - массив объектов, каждый из которых описывает одну премиум-опцию.
+
request example:
 +
<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
  
<tt> id (string) </tt> - идентификатор опции
+
<nowiki>{"result": null, "error": "error description"}</nowiki>
  
<tt> name (string) </tt> - название опции
+
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
  
<tt> valid_from (integer) </tt> - дата, с которой опция активна (unix timestamp)
+
===check_user_service===
 +
Check whether the specified option is enabled on the engine.
  
<tt> valid_to (integer) </tt> - дата, по которую опция активна (unix timestamp)
+
parameters:
 +
* '''id''' (''string'') - option ID
  
<tt> trial (boolean) </tt> - true, если опция активирована бесплатно на тестовый период
+
request example:
 +
<nowiki>http://localhost:6878/webui/api/service?method=check_user_service&id=noAds</nowiki>
  
<tt> description (string) </tt> - описание опции
+
Response format - boolean value.
 +
Example (option is not activated):
 +
 
 +
<nowiki>{
 +
"result": false,
 +
"error": null
 +
}</nowiki>
 +
 
 +
or
 +
 
 +
<nowiki>{"result": null, "error": "error description"}</nowiki>

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