Создание сервиса 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. Каждый метод выполняет свое бизнес-действие, заложенное в соответствующей хранимой процедуре.

Входящие запросы API

Это обработка на сайте запросов от внешних систем.

См. отдельную статью про входящие запросы API

Исходящие запросы к внешним API

Это отправка запросов с сайта к API других систем.

См. отдельную статью про исходящие запросы API 

Дополнительные материалы

1. Программное взаимодействие через API между 2 разными экземплярами Falcon
2. Как выводить и обрабатывать данные на форме из внешнего источника через API
3. Как вывести данные из удаленного источника (по API) в компоненте Таблица
4. Как учесть в отклике результат внешних действий в API
5. Полезные SQL функции для API
6. Как создать цепочку последовательных вызовов API методов