Difference between revisions of "Engine Service API"

From Ace Stream Wiki
Jump to: navigation, search
Line 1: Line 1:
−
== Методы, которые можно использовать при разработке продуктов, предназначенных для премиум-пользователей и/или которые будут распространяться под индивидуальной лицензией ==
+
==Общее описание==
 +
Сервисное API движка предназначено в первую очередь для предоставления сторонним приложениям возможности узнать, активированы ли какие-либо премиум-опции для движка, с которым работает приложение. Также API предоставляет возможность активировать нужную опцию от имени приложения.
  
−
Для проверки ключа пользователя, загрузки расширения и получения списка активированных опций используется веб-интерфейс движка, который работает на порту 6878.
+
Сервисное API движка работает на порту 6878, если не указан другой порт опцией <tt>--http-port</tt>.
  
−
Запросы отсылаются методами HTTP GET либо POST, ответы в формате JSON.
+
API работает по протоколу HTTP. Запросы отсылаются на адрес <tt><nowiki>http://localhost:6878/webui/api/service</nowiki></tt>
  
−
Файл-расширение можно получить с помощью API реселлера:
+
Ответы в формате JSON.
−
http://wiki.acestream.org/wiki/index.php/Reseller_API
 
  
−
Добавили на вики описание метода API для создания ключа пользователя:
+
==Методы API==
−
http://wiki.acestream.org/wiki/index.php/Reseller_API#createUserKey
 
  
 +
Каждый запрос к API должен иметь обязательный параметр <tt>method</tt>, содержащий название вызываемого метода.
  
−
Метод API createUserkey позволяет создавать ключи двух разных типов. Тип ключа задается параметром type:
+
Ниже приведен список всех доступных методов.
  
−
'''<tt> type=1 </tt>''' - общий ключ, который обеспечит пользователю получения необходимого Премиум-статуса, для работы с любыми приложениями и отключение определенных форматов рекламы  (такой ключ работает на любых устройствах с любыми приложениями)
+
===check_user_key===
 +
Проверить, загружен ли указанный ключ пользователя в движок.
  
−
'''<tt> type=2 </tt>''' - ключ для индивидуальной лицензии, который будет работать только с указанным приложением.
+
параметры:
 +
* '''key''' (''string'') - ключ пользователя
  
 +
варианты ответов:
 +
* '''{"status": "ok"}''' - указанный ключ загружен в движок
 +
* '''{"status": "not_found"}''' - указанный ключ не загружен в движок
 +
* '''{“status”: “error”, "error": "error description"}''' - при обработке запроса возникла ошибка
  
−
При создании ключа с типом 2 в запросе обязательно должен быть указан параметр <tt> product </tt> (идентификатор продукта, к которому должен быть привязан ключ).
+
пример запроса:
 +
<nowiki>http://localhost:6878/webui/api/service?method=check_user_key&user_key=1111-2222-3333-4444</nowiki>
  
−
Идентификатор продукта можно будет узнать на сайте acccounts.acestream.net (пока этот раздел недоступен мы можем выдавать идентификаторы по запросу).
+
ответ:
 +
<nowiki>{"status": "not_found"}</nowiki>
  
−
Чтобы стать реселлером, нужно зарегистрироваться у нас на сайте и зайти по ссылке:
+
===check_product_user_keys===
−
https://accounts.acestream.net/reseller
+
Проверка наличия ключей пользователя для конкретного продукта.
  
−
Откроется форма регистрации реселлера, нужно нажать "зарегистрироваться", после этого мы получим письмо про регистрацию нового реселлера и поставим ему статус "подтвержден". После этого по ссылке https://accounts.acestream.net/reseller будут доступны все инструменты для реселлера.
+
параметры:
 +
* '''product_key''' (''string'') - публичная часть ключа продукта
  
 +
варианты ответов:
 +
* '''{"status": "ok"}''' - в движок загружен как минимум один ключ для указанного приложения
 +
* '''{"status": "not_found"}''' - ключей для указанного приложения нет
 +
* '''{“status”: “error”, "error": "error description"}''' - при обработке запроса возникла ошибка
  
−
'''Предлагается следующая схема работы''' (п.2 - работает для версии движка 2.2.1-Next и 3.0.0 Beta):
+
пример запроса:
 +
<nowiki>http://localhost:6878/webui/api/service?method=check_product_user_keys&product_key=1111</nowiki>
  
−
'''1) Проверка ключа пользователя:'''
+
ответ:
−
http://127.0.0.1:6878/webui/app/check-user-key?key=<user_
+
<nowiki>{"status": "ok"}</nowiki>
−
key>
 
  
−
Варианты ответов:
+
===load_extension===
 +
Загрузка файла-расширения в движок
  
−
* если указанный ключ загружен в движок:
+
Чтобы загрузить файл расширения в движок, нужно отправить POST запрос на адрес <nowiki>http://localhost:6878/webui/api/service?method=load_extension</nowiki>
−
  {"status": "ok"}
 
  
−
* если указанный ключ не загружен в движок:
+
В теле запроса нужно передать содержимое файла расширения, полученное с помощью метода API для реселлеров [[Reseller_API#createUserKey|createUserKey]]
−
  {"status": "not_found"}
 
  
−
* если при обработке запроса возникла ошибка:
+
варианты ответов:
−
  {"error": "error description"}
+
* '''{"status": "ok"}''' - расширение успешно загружено в движок
 +
* '''{“status”: “error”, "error": "error description"}''' - при обработке запроса возникла ошибка
 +
 
 +
пример запроса:
 +
<nowiki>http://localhost:6878/webui/api/service?method=load_extension</nowiki>
  
−
'''2) Чтобы загрузить файл расширения в движок, нужно отправить POST запрос на этот адрес:'''
+
ответ:
−
http://127.0.0.1:6878/webui/app/load-extension
+
<nowiki>{"status": "ok"}</nowiki>
  
−
В теле запроса нужно передать содержимое файла расщирения.
+
===get_services===
 +
Получить список премиум-опций, активированных на движке.
  
−
Варианты ответов:
+
Если передается параметр <tt>product_key</tt>, то возвращается список опций, доступных для всех приложений, а также опций, доступных только для указанного приложения.
  
−
- если расширение успешно загружен в движок:
+
Если параметр <tt>product_key</tt> не передается, то возвращается только список опций, доступных для всех приложений.
−
  {"status": "ok"}
 
  
−
- если при обработке запроса возникла ошибка:
+
параметры:
−
  {"error": "error description"}
+
* '''product_key''' (''string'') - необязательный параметр, в котором передается публичная часть ключа продукта
  
−
'''3) Получение списка премиум-опций, активированных на движке:'''
+
пример запроса:
−
http://127.0.0.1:6878/webui/app/services/get
+
<nowiki>http://localhost:6878/webui/api/service?method=get_services&product_key=1111</nowiki>
  
 
Формат ответа - массив объектов, каждый из которых описывает одну премиум-опцию.
 
Формат ответа - массив объектов, каждый из которых описывает одну премиум-опцию.
−
 
 
Пример:
 
Пример:
  
−
  [
+
  <nowiki>{
 +
“status”: “ok”,
 +
“services”:
 +
[
 
   {
 
   {
−
  "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"
 
   }
 
   }
−
]
+
]
 +
}</nowiki>
 +
 
 +
или
  
−
'''Поля:'''
+
<nowiki>{“status”: “error”, “error”: “error description”}</nowiki>
  
−
* '''<tt> id (string) </tt>''' - идентификатор опции
+
Поля:
−
* '''<tt> name (string) </tt>''' - название опции
+
* '''id''' (''string'') - идентификатор опции
−
* '''<tt> valid_from (integer) </tt>''' - дата, с которой опция активна (unix timestamp)
+
* '''name''' (''string'') - название опции
−
* '''<tt> valid_to (integer) </tt>''' - дата, по которую опция активна (unix timestamp)
+
* '''valid_from''' (''integer'') - дата, с которой опция активна (unix timestamp)
−
* '''<tt> trial (boolean) </tt>''' - true, если опция активирована бесплатно на тестовый период
+
* '''valid_to''' (''integer'') - дата, по которую опция активна (unix timestamp)
−
* '''<tt> description (string) </tt>''' - описание опции
+
* '''trial''' (''boolean'') - true, если опция активирована бесплатно на тестовый период
 +
* '''description''' (''string'') - описание опции

Revision as of 15:42, 27 May 2014

Общее описание

Сервисное API движка предназначено в первую очередь для предоставления сторонним приложениям возможности узнать, активированы ли какие-либо премиум-опции для движка, с которым работает приложение. Также API предоставляет возможность активировать нужную опцию от имени приложения.

Сервисное API движка работает на порту 6878, если не указан другой порт опцией --http-port.

API работает по протоколу HTTP. Запросы отсылаются на адрес http://localhost:6878/webui/api/service

Ответы в формате JSON.

Методы API

Каждый запрос к API должен иметь обязательный параметр method, содержащий название вызываемого метода.

Ниже приведен список всех доступных методов.

check_user_key

Проверить, загружен ли указанный ключ пользователя в движок.

параметры:

  • key (string) - ключ пользователя

варианты ответов:

  • {"status": "ok"} - указанный ключ загружен в движок
  • {"status": "not_found"} - указанный ключ не загружен в движок
  • {“status”: “error”, "error": "error description"} - при обработке запроса возникла ошибка

пример запроса: 

http://localhost:6878/webui/api/service?method=check_user_key&user_key=1111-2222-3333-4444

ответ: 

{"status": "not_found"}

check_product_user_keys

Проверка наличия ключей пользователя для конкретного продукта.

параметры:

  • product_key (string) - публичная часть ключа продукта

варианты ответов:

  • {"status": "ok"} - в движок загружен как минимум один ключ для указанного приложения
  • {"status": "not_found"} - ключей для указанного приложения нет
  • {“status”: “error”, "error": "error description"} - при обработке запроса возникла ошибка

пример запроса: 

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

ответ: 

{"status": "ok"}

load_extension

Загрузка файла-расширения в движок

Чтобы загрузить файл расширения в движок, нужно отправить POST запрос на адрес http://localhost:6878/webui/api/service?method=load_extension

В теле запроса нужно передать содержимое файла расширения, полученное с помощью метода API для реселлеров createUserKey

варианты ответов:

  • {"status": "ok"} - расширение успешно загружено в движок
  • {“status”: “error”, "error": "error description"} - при обработке запроса возникла ошибка

пример запроса: 

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

ответ: 

{"status": "ok"}

get_services

Получить список премиум-опций, активированных на движке.

Если передается параметр product_key, то возвращается список опций, доступных для всех приложений, а также опций, доступных только для указанного приложения.

Если параметр product_key не передается, то возвращается только список опций, доступных для всех приложений.

параметры:

  • product_key (string) - необязательный параметр, в котором передается публичная часть ключа продукта

пример запроса: 

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

Формат ответа - массив объектов, каждый из которых описывает одну премиум-опцию. Пример: 

{
“status”: “ok”,
“services”:
[
  {
    "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"
  }
]
}

или 

{“status”: “error”, “error”: “error description”}

Поля:

  • id (string) - идентификатор опции
  • name (string) - название опции
  • valid_from (integer) - дата, с которой опция активна (unix timestamp)
  • valid_to (integer) - дата, по которую опция активна (unix timestamp)
  • trial (boolean) - true, если опция активирована бесплатно на тестовый период
  • description (string) - описание опции
Retrieved from "https://wiki.acestream.media/index.php?title=Engine_Service_API&oldid=323"