Создание сервиса API для сайта. Программный интерфейс веб-платформы

Введение в API

В системе реализованы 2 механизма для работы API

Входящий запрос к методу API платформы - внешняя система обращается по определенному endpoint платформы по HTTPS GET/POST и получает некий отклик в JSON/XML/Plain text формате.
Исходящий запрос к внешним системам - система подготавливает запрос к внешней системе (URL, параметры формы, HTTP заголовки и др.) в процедуре Request, отправляет его по HTTPS GET/POST и обрабатывает ответ в процедуре Response.

Подготовка исходящих запросов, обработка отклика от исходящих запросов, обработка входящих запросов - вся обработка происходит через хранимые процедуры.

Некоторые готовые интеграции на базе платформы:

Варианты интеграции с внешним API

Есть несколько вариантов/уровней интеграции:

1. Вызов неких действий через кнопку Формы.

Используем процедуру SaveItem формы для вызова Внешнего действия apirequest, которое непосредственно выполняет запрос к внешней среде.

Полученный ответ может быть обработан через spCallback (хранимая процедура, которая выполняется после указанного внешнего действия), либо через JS коллбек формы SaveItem (в JS обрабатываем JSON-поле additionalData).

2. Кастом JS компонент.

Реализовать свой JS компонент, который обращается через Request JS к базе данных. В хранимой процедуре вызываем внешнее действие apirequest, затем обрабатываем отклик через JS.

3. Подтягивание данных по API из внешней системы при загрузке формы или таблицы.

Если указан источник у формы, таблицы, то при загрузке таблицы сначала выполняется запрос в внешней системе, затем данные попадают в процедуру GetItems, где вы можете их распарсить и вывести как данные таблицы.

4. Вебхук.

Допустим, произошло некое событие в системе. Вызываем в процедурах sync, форме или другом месте внешнее действие apirequest, которое отправляет уведомление (информацию о событии в виде Get/Post запроса) во внешнюю систему.

5. Прямой доступ к БД

В некоторых случаях можно интегрировать 2 системы минуя слой API.

Платформа может обращаться напрямую к другим СУБД (через SQL Server Linked Server). Запросы также будут писаться на SQL как и в обычном случае, но обработка данных будет уже происходить во внешней системе.

Если есть другая БД MS SQL Server, которая лежит на том же сервере, то можно дать права на некие объекты этой БД пользователю платформы. В этом случае работа практически ничем не будет отличаться от случая, когда мы используем родную базу Falcon Space (только префикс будет у таблиц добавляться с именем базы данных).

Интерфейс управления API в личном кабинете администратора

Управление API происходит на странице /asapi.

Управление входящими запросами:

Управление исходящими запросами:

Тестирование запросов по аналогии с Postman (кнопка API Request):

Заполняем URL и параметры запроса (HTTP заголовки, файлы, параметры формы) и получаем отклик внешней системы.

Что может и не может API платформы

Что может механизм API

Отправлять исходящие запросы GET/POST
Отправлять свои HTTP заголовки
Отправлять данные формы
Отправлять тело POST запроса в виде JSON
Отправлять файлы в POST запросе
Проводить тестовые запросы (по аналогии с postman)
Делать свой слой API для обращения к ним извне
Вводить авторизацию для входящих API запросов по токену(api пользователи и сессионные ключи для доступа, предварительные запросы для получения токена).
Логирование API запросов (по каждому запросу сохраняется input и output данные в trace).

Что не может API платформы

Работа в формате SOAP (технически возможно, но очень трудоемко поддерживать сложный XML формат вручную).
Система не использует разделение GET/POST/DELETE/PUT запросов для обработки сущностей по соглашениям REST. Каждый метод выполняет свое бизнес-действие, заложенное в соответствующей хранимой процедуре.