Документация для разработчиков

Назначение

Simplit.io меняет принцип взаимодействия клиента и сервера.

Для взаимодействия с внешним миром, многие облачные сервисы используют REST API. У этого метода есть как достоинства, так и недостатки.

HTTP-соединение является условно-постоянным и после ответа на запрос клиента, сервер разрывает соединение.

Для поддержания HTTP-соединения используются различные хаки - chunked, streaming. А для эмуляции асинхронных вызовов используется механизм WebHooks.

Simplit.io решает эти проблемы кардинально - сервис преобразует REST в Realtime. Клиент получает постоянное WebSocket-соединение, а передаваемые данные конвертируются в формат, понятный для облачного сервиса.

В качестве дополнительного бонуса, Simplit.io уменьшает overhead. Детальное сравнение можно прочитать в статье REST vs WebSocket

Обычная схема (без использования Simplit.io)

При обычном подходе, клиент с определенной периодичностью "бомбит" запросами REST API облачного сервиса, задавая одни и те же вопросы:
«Есть что-то новое?»

А так как большинство REST API облачных сервисов используют механизм WebHook, то клиенту приходится "бомбить" запросами еще и собственную базу данных: «Есть новый WebHook?»

Кроме того, на стороне клиента должен быть установлен веб-сервер (Apache, IIS), который сконфигурирован для принятия WebHooks.

Схема с использованием Simplit.io

Всю «черновую» работу выполняет Simplit.io, а клиент получает уже готовые Push-уведомления.

Клиент использует только одно WebSocket-соединение. Применяется чистый WebSocket (RFC 6455) без каких-либо надстроек.

API (формат обмена)

Для обмена данными используется формат JSON. Протокол передачи предельно простой.

Пакет запроса:

{
  "service": "service_name",
  "data": {...}
}

Пакет ответа / события:

{
  "service": "service_name",
  "event": "event_name",
  "data": {...}
}

Запросы

Общий формат запросов

{
  "service": "service_name",
  "data": {...}
}

  • service - (обязательный), имя сервиса
  • data - (обязательный), данные отправляемые сервису

Детализация параметра data:

Состав параметра data зависит от потребностей REST API конечного сервиса. Часть параметров являются опциональными.

{
  "url": "",
  "header": {},
  "method": "",
  "data": ""
}

  • url - (обязательный для REST), URL для запроса к REST-сервису
  • header - (необязательный), доп. параметры заголовка запроса к REST в формате {"key":"value"}
  • method - (обязательный), метод для REST: [get,post,put,delete], для WS: [connect,command]
  • data - (обязательный), данные в том виде, который требуется для конечного сервиса. Допускается пустое значение.

События

Общий формат событий

{
  "service": "service_name",
  "event": "event_name",
  "data": {...}
}

  • service - (обязательный), имя сервиса
  • event - (обязательный), имя события
  • data - (обязательный), полученные данные

Примеры

Ниже, приведены пакеты запросов к облачным сервисам.

Запрос баланса Zadarma

{
  "service": "zadarma",
  "data": {
    "url": "https://api.zadarma.com/v1/info/balance/?format=json",
    "header": {"Authorization": "API_KEY:NGU14NTUxNDFhNWE0YMzY1YTY1Mg=="},
    "method": "POST",
    "data":""
}

Запрос статистики звонков АТС Mango-Office

{
  "service": "mango",
  "data": {
    "url": "https://app.mango-office.ru/vpbx/stats/request",
    "header": {"Content-type":"application/x-www-form-urlencoded"},
    "method": "POST",
    "data":"vpbx_api_key=%3C_API_KEY_%3E&sign=12345665d77481b86e&json=%7B%22date_from%22%3A%221445288400%22%2C%22date_to%22%3A%221445374859%22%7D"
}

Запрос внутренних номеров АТС OnlinePBX (REST)

{
  "service": "onpbx-rest",
  "data": {
    "url": "https://api.onlinepbx.ru/simplit.onpbx.ru/user/get.json",
    "header":
     {"x-pbx-date": "2016-01-11 14:05:02",
     "Accept": "application/json",
     "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8;",
     "Content-MD5": "d41d8cd98f00b204e9800998ecf8427e",
     "x-pbx-authentication": "KEY_ID:NmI0ZGViYWY4MWM2Yg=="},
    "method": "POST",
    "data":""
}