Что такое REST API и как он работает?

REST API (Representational State Transfer Application Programming Interface) — это стандартизированный способ взаимодействия между системами через HTTP-протокол. API HubEx работает по принципу клиент-серверной архитектуры:

1. Клиент (ваше приложение) отправляет HTTP-запрос к серверу HubEx

2. Сервер обрабатывает запрос и возвращает ответ в стандартном формате (обычно JSON)

3. Обмен данными происходит через четко определенные конечные точки (endpoints)

Основные принципы работы:

• Статусность: Каждый запрос содержит всю необходимую информацию для его обработки

• Кэширование: Ответы могут кэшироваться для повышения производительности

• Единообразие интерфейса: Все ресурсы доступны через стандартные HTTP-методы

• Слоистая архитектура: Промежуточные серверы (прокси, балансировщики) могут участвовать в обработке запроса

Основные типы HTTP-запросов в REST API

1. GET — Получение данных

Что делает: Запрашивает данные с сервера
Использование: Получение информации (списки заявок, детали объекта и т.д.)
Особенности:

• Безопасный и идемпотентный запрос (не изменяет данные)

• Параметры передаются в URL (фильтры, пагинация)

• Пример: GET /fsm/WORK/Tasks — список заявок

2. POST — Создание данных или выполнение действий

Что делает: Отправляет данные для создания новой записи
Использование: Создание объектов, выполнение операций
Особенности:

• Содержит тело запроса (обычно JSON)

• Не идемпотентен (повторный запрос создаст новый объект)

• Пример: POST /fsm/AUTHZ/AccessTokens — получение токена доступа

3. PUT — Полное обновление данных

Что делает: Полная замена существующего объекта
Использование: Обновление всех полей объекта
Особенности:

• Требует полного представления объекта

• Идемпотентен

• Пример: PUT /fsm/WORK/Tasks/{id} — полное обновление заявки

4. PATCH — Частичное обновление

Что делает: Обновляет только указанные поля
Использование: Модификация отдельных атрибутов
Особенности:

• Экономит трафик и упрощает обновления

• Идемпотентен

• Пример: PATCH /fsm/WORK/Tasks/{id} — изменение статуса заявки

5. DELETE — Удаление данных

Что делает: Удаляет указанный объект
Использование: Удаление записей из системы
Особенности:

• Идемпотентен

• Пример: DELETE /fsm/WORK/Tasks/{id} — удаление заявки

Примеры сценариев интеграции с популярными системами

1. CRM-системы (Bitrix24, amoCRM)

Сценарии:

• Создание заявок в HubEx из лидов CRM

• Синхронизация статусов заявок

• Обмен данными о клиентах

Рекомендации:

• Используйте вебхуки CRM для триггеров событий

• Для двусторонней синхронизации настройте регулярные GET-запросы

• Пример интеграции: POST /fsm/WORK/Tasks при создании лида

2. Системы учета (1С, SAP)

Сценарии:

• Импорт оборудования и активов

• Синхронизация данных о ремонтах

• Учет материалов и запчастей

Рекомендации:

• Используйте пакетные операции для массовой загрузки

• Настройте расписание синхронизации (например, раз в час)

• Пример: GET /fsm/ES/assets для получения списка оборудования

3. Мессенджеры и уведомления (Telegram, Slack)

Сценарии:

• Оповещения о новых заявках

• Уведомления об изменении статусов

• Отправка отчетов

Рекомендации:

• Используйте webhook-уведомления HubEx

• Для Telegram настройте бота с long-polling

• Пример: GET /fsm/WORK/Tasks?isClosed=false для мониторинга открытых заявок

4. Системы мониторинга (Zabbix, PRTG)

Сценарии:

• Автоматическое создание заявок при инцидентах

• Обновление статусов при восстановлении

• Привязка оборудования к заявкам

Рекомендации:

• Используйте скрипты-обертки для преобразования форматов

• Настройте фильтрацию по критичности событий

• Пример: POST /fsm/WORK/Tasks при срабатывании триггера

5. Мобильные приложения

Сценарии:

• Просмотр и создание заявок

• Фотофиксация проблем

• Геолокация объектов

Рекомендации:

• Используйте OAuth 2.0 для авторизации

• Оптимизируйте запросы для мобильных сетей

• Пример: PATCH /fsm/WORK/Tasks/{id} для обновления статуса с телефона

 

Дополнительная информация по API

1. Обработка ошибок: Всегда проверяйте HTTP-статус ответа

   • 200-299 — успех

   • 400-499 — ошибка клиента

   • 500-599 — ошибка сервера

2. Пагинация: Для больших наборов данных используйте параметры fetch и offset

3. Кэширование: Сохраняйте часто запрашиваемые данные локально

4. Ограничение частоты запросов: Не превышайте лимиты API (обычно 60 запросов в минуту)

5. Безопасность: Никогда не храните токены в открытом виде

6. Логирование: Ведите журнал всех запросов и ответов для отладки

7. Асинхронные операции: Для длительных процессов используйте webhook-уведомления

---

Следующие шаги:

• Начало работы с REST API HubEx

---

• Перейти в меню