Difference between revisions of "Engine Service API"

From Ace Stream Wiki
Jump to: navigation, search
 
(9 intermediate revisions by one other user not shown)
Line 1: Line 1:
==Общее описание==
+
==Common description==
Сервисное API движка предназначено в первую очередь для предоставления сторонним приложениям возможности узнать, активированы ли какие-либо премиум-опции для движка, с которым работает приложение. Также API предоставляет возможность активировать нужную опцию от имени приложения.
+
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.
  
Сервисное API движка работает на порту 6878, если не указан другой порт опцией <tt>--http-port</tt>.
+
Engine service API works at port 6878, if any other port is not specified with option <tt>--http-port</tt>.
  
API работает по протоколу HTTP. Запросы отсылаются на адрес <tt><nowiki>http://localhost:6878/webui/api/service</nowiki></tt>
+
API works via HTTP protocol. Requests are sent to the address <tt><nowiki>http://localhost:6878/webui/api/service</nowiki></tt>
  
Ответы в формате JSON.
+
Responds are in JSON format, as JSON-RPC, but without id.
  
==Методы API==
+
==API methods==
  
Каждый запрос к API должен иметь обязательный параметр <tt>method</tt>, содержащий название вызываемого метода.
+
Each request to API must have required parameter <tt>method</tt> that contains a name of  the called method.
  
Ниже приведен список всех доступных методов.
+
Below you can see a list of all available methods.
  
 
===check_user_key===
 
===check_user_key===
Проверить, загружен ли указанный ключ пользователя в движок.
+
Check, if specified user key is downloaded to the engine.
  
параметры:
+
parameters:
* '''key''' (''string'') - ключ пользователя
+
* '''user_key''' (''string'') - user key
  
варианты ответов:
+
response options:
* '''{"status": "ok"}''' - указанный ключ загружен в движок
+
* '''{"result": "ok", "error": null}''' - specified key is downloaded to the engine
* '''{"status": "not_found"}''' - указанный ключ не загружен в движок
+
* '''{"result": "not_found", "error": null}''' - specified key is not downloaded to the engine
* '''{“status”: “error”, "error": "error description"}''' - при обработке запроса возникла ошибка
+
* '''{"result": null, "error": "error description"}''' - during query processing error was occurred
  
пример запроса:
+
request example:
  <nowiki>http://localhost:6878/webui/api/service?method=check_user_key&user_key=1111-2222-3333-4444</nowiki>
+
  <nowiki>http://localhost:6878/webui/api/service?method=check_user_key&user_key=1179fcb364f83cc30150b3daffd55ae0a6b70fea</nowiki>
  
ответ:
+
response:
  <nowiki>{"status": "not_found"}</nowiki>
+
  <nowiki>{"result": "not_found", "error": null}</nowiki>
  
 
===check_product_user_keys===
 
===check_product_user_keys===
Проверка наличия ключей пользователя для конкретного продукта.
+
Check availability of user keys for a specific product.
  
параметры:
+
parameters:
* '''product_key''' (''string'') - публичная часть ключа продукта
+
* '''product_key''' (''string'') - public part of the product key
  
варианты ответов:
+
response options:
* '''{"status": "ok"}''' - в движок загружен как минимум один ключ для указанного приложения
+
* '''{"result": "ok", "error": null}''' - at least one key for a specified application was downloaded to the engine
* '''{"status": "not_found"}''' - ключей для указанного приложения нет
+
* '''{"result": "not_found", "error": null}''' - there are no keys for a specified application
* '''{“status”: “error”, "error": "error description"}''' - при обработке запроса возникла ошибка
+
* '''{"result": null, "error": "error description"}''' - during query processing error was occurred
  
пример запроса:
+
request example:
 
  <nowiki>http://localhost:6878/webui/api/service?method=check_product_user_keys&product_key=1111</nowiki>
 
  <nowiki>http://localhost:6878/webui/api/service?method=check_product_user_keys&product_key=1111</nowiki>
  
ответ:
+
response:
  <nowiki>{"status": "ok"}</nowiki>
+
  <nowiki>{"result": "ok", "error": null}</nowiki>
  
 
===load_extension===
 
===load_extension===
Загрузка файла-расширения в движок
+
Loading extension [[extension string]] into the app engine
  
Чтобы загрузить файл расширения в движок, нужно отправить POST запрос на адрес <nowiki>http://localhost:6878/webui/api/service?method=load_extension</nowiki>
+
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>
  
В теле запроса нужно передать содержимое файла расширения, полученное с помощью метода API для реселлеров [[Reseller_API#createUserKey|createUserKey]]
+
In body of the request you have to transfer contents of the extension string.
  
варианты ответов:
+
response options:
* '''{"status": "ok"}''' - расширение успешно загружено в движок
+
* '''{"result": true, "error": null}''' - extension was successfully loaded to the engine
* '''{“status”: “error”, "error": "error description"}''' - при обработке запроса возникла ошибка
+
* '''{"result": null, "error": "error description"}''' - during query processing error was occurred
 
    
 
    
пример запроса:
+
request example:
 
  <nowiki>http://localhost:6878/webui/api/service?method=load_extension</nowiki>
 
  <nowiki>http://localhost:6878/webui/api/service?method=load_extension</nowiki>
  
ответ:
+
response:
  <nowiki>{"status": "ok"}</nowiki>
+
  <nowiki>{"result": true}</nowiki>
  
 
===get_services===
 
===get_services===
Получить список премиум-опций, активированных на движке.
+
Get a list of premium options activated on the engine.
  
Если передается параметр <tt>product_key</tt>, то возвращается список опций, доступных для всех приложений, а также опций, доступных только для указанного приложения.
+
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.
  
Если параметр <tt>product_key</tt> не передается, то возвращается только список опций, доступных для всех приложений.
+
If parameter <tt>product_key</tt> is not transferred, only list of options available for all applications comes back.
  
параметры:
+
parameters:
* '''product_key''' (''string'') - необязательный параметр, в котором передается публичная часть ключа продукта
+
* '''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>
 
  <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>{
 
  <nowiki>{
“status”: “ok”,
+
"result":
“services”:
 
 
[
 
[
 
   {
 
   {
Line 94: Line 93:
 
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>
 
}</nowiki>
  
или
+
or
  
  <nowiki>{“status”: “error”, “error”: “error description”}</nowiki>
+
  <nowiki>{"result": null, "error": "error description"}</nowiki>
  
Поля:
+
Fields:
* '''id''' (''string'') - идентификатор опции
+
* '''id''' (''string'') - option ID
* '''name''' (''string'') - название опции
+
* '''name''' (''string'') - option name
* '''valid_from''' (''integer'') - дата, с которой опция активна (unix timestamp)
+
* '''valid_from''' (''integer'') - date of option activation (unix timestamp)
* '''valid_to''' (''integer'') - дата, по которую опция активна (unix timestamp)
+
* '''valid_to''' (''integer'') - date untill which option is active (unix timestamp)
* '''trial''' (''boolean'') - true, если опция активирована бесплатно на тестовый период
+
* '''trial''' (''boolean'') - true, if option was activated for free for a trial period
* '''description''' (''string'') - описание опции
+
* '''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
 +
 
 +
<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"}