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

Призначення

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