Создание сервиса 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 платформы, к которому обращается внешняя система через запросы GET/POST.
Как проходит основной процесс входящего запроса:
- Обращение извне по HTTPS GET к методу auth для получения token доступа (система проверяет логин, пароль и выдает токен, который будет проверяться в дальнейших обращениях).
- Отправка запроса action для выполнения некоего действия (Получить заказы, создать новый заказ). В рамках запроса происходит следующее:
- Проверяются права на выполнение операции
- Запускается хранимая процедура обработки действия, подготавливается ответ для вызывающей стороны в виде JSON, XML, Plain text.
- Выдается некий отклик на вызывающую сторону
Всегда лучше использовать коды для API только в нижнем регистре латиницей и без пробелов. Таким образом уменьшаются риски проблем с url rewrite неверных адресов
Для API используются обычные HTTPS запросы с ответом в формате JSON. Основные методы
-
auth - создание сессии пользования API (параметры username, password)
-
action - выполнение некоего метода API (параметры могут быть любые)
Использование API
1. Вызываем по Get или Post метод авторизации /api/auth?username=&password={password}&output=json
-
Имя и пароль пользователя API задается в таблице as_api_users (это не логин/пароль обычного пользователя системы).
-
output - необязательный параметр, задает формат вывода (json, xml,text).
Если есть ошибки, то result = false и errorCode содержит код ошибки.
2. Вызываем метод API
/api/action/getOrders?token=7285440B-BD32-405F-813D-C26DFED23DF5&catID=1
Передаем token, action (код метода) и произвольные параметры.
Коды ошибок и описания к ним:
№ |
Код |
Описание ошибки |
1 |
100 |
Неверный токен |
2 |
101 |
Истекло время сессии |
3 |
102 |
Не найдена реализация метода АПИ (т.е. нет хранимой процедуры метода) |
4 |
103 |
Выполнение метода завершилось с ошибкой |
5 |
104 |
Имя/пароль неверные |
- в ExtendedDictionaryParameter @parameters используем Key, Value2, а не Key, Value!
- в @parameters также передается содержимое самого запроса Request.InputStream (в Key=InputStream)
- в @parameters также передается ключ remoteIP - IP вызывающей стороне (например, по нему можно проверить легитимность запроса к API)
-
Если используете для отправки метод POST, то обязательно указывайте 'content-type': 'application/x-www-form-urlencoded'. Проверять подобные запросы можно через программу postman.
Создание нового метода API
API создается следующим образом:
-
Создается действие в таблице as_api_actions (на странице /asapi)
- entityCode указывает код сущности, с которой мы работаем, например order.
- code - задает код действия.
2. Создается хранимая процедура api_{entityCode}_{code}, которая реализует основную логику метода API.
CREATE procedure [dbo].[api_order_getOrders]
@parameters ExtendedDictionaryParameter READONLY, -- параметры которые переданы в метод
@username nvarchar(256) --пользователь API (это не логин пользователя в системе)
as
begin
declare @catID int
select @catID = cast(Value2 as int) from @parameters where [Key] = 'catID'
/* select 1 - это информация об операции. В errorCode можно указать
специфичные коды ошибок по операциям */
select '' Msg, 1 Result, 0 errorCode, 0 onlyData
/* select 2 - это данные, которые необходимо передать источнику запроса к API
(в выходном JSON передаются в параметре data) */
select * from ord_orders
/* SELECT 3 Вызов внешних действий (напр Запрос API)*/
end
На входе:
- @parameters - входные параметры в API метод (что приходит из URL, из полей формы и коллекции Httpheaders). Также здесь хранится тело запроса с кодом Key = "InputStream"
- @username - логин API (важно его не путать с логином пользователя в системе).
На выходе:
- SELECT 1:
- результат операции (Result),
- код результата (errorCode),
- HTTP код ответа (httpCode, по умолчанию идет 200),
- редирект на какой-то адрес (redirectUrl),
- onlyData - если 1, то для JSON и XML вывода данные будут формироваться чисто из данных из SELECT 2
- SELECT 2 - произвольные данные, которые передаются вовне.
- SELECT 3 - Вызов внешних действий (уведомление на почту, телеграм и др.)
Вызов API без авторизации
В этом случае нет необходимости использовать токены.
-
У action укажите параметр withoutToken=true.
-
Вызывайте метод без токена: /api/action/getOrders?catID=1
Установка формата вывода для действия.
Для этого укажите json,text или xml в параметре outputType для действия (as_api_actions).
Cвойство идемпотентности для создаваемых методов API
Для включения идемпотентности необходимо в запросе к API передавать определенный параметр или заголовок(например X-Request-ID), содержащий уникальный идентификатор: guid, комбинация из номера заказа, даты и суммы.
Каждый новый запрос, который необходимо обработать, должен включать новое значение X-Request-ID.
Таким образом можно избежать проблем с повторными запросами (когда операция дважды выполнится на сервере для 1 запроса).
Иногда требуется учесть в выходном сообщении результаты выполнения внешних действий, в этом случае необходимо задействовать дополнительную процедуру _result - https://falconspace.ru/docs/vkhodyashchiy-api--kak-uchest-v-otklike-rezultat-vneshnikh-deystviy-v-api
Исходящие запросы к внешним API
Чтобы создать запрос, необходимо выполнить следующее:
-
создать запись о новом запросе (таблицы Исходящие запросы API на /asapi)
-
реализовать процедуру request(она выдает адрес и параметры для выполнения запроса)
-
На входе: @parameters ExtendedDictionaryParameter (коллекция входных параметров в Key nvarchar(32), Value2 nvarchar(max)) и @username (текущий пользователь)
-
Возвращает SELECT 1 (Msg, Result и URL, ContentType)
- URL - адрес, который будет вызван по HTTPS
- RequestParameterForResponse - некая строка, которую потом можно извлечь в процедуре respose по одноименному ключу из @parameters. В исходящий запрос эта информация не идет.
- ContentType - можно задать для POST запросов свой ContentType (для формы).
- По умолчанию он подставляется для форм multipart/form-data; boundary=------
- и для json тела application/json
-
и SELECT 2 (параметры которые будут передаваться вовне - name, value, type).
-
type - вариант form, header, json.
-
Если отправить надо post запрос, то параметры ставьте в form.
-
Если передан json (используется для POST, имя можно также ставить в JSON) - то его содержимое будет телом всего запроса POST. Все остальные параметры типа Form в этом случае игнорируются (при этом параметры типа headers не игнорируются).
-
Если нужны обычные get параметры - то передавайте их через URL
-
-
-
-
реализовать процедуру обработки ответа - response
-
На входе ответ от внешнего источника в виде строки @response, @parameters ExtendedDictionaryParameter (коллекция входных параметров в Key, Value2, которые приходили в Request процедуру. Сюда также приходит от Request параметр RequestParameterForResponse)
-
Ответ
-
SELECT 1 Msg, Result и Response (может быть дополнительная обработка и выдача ответа вовне).
- SELECT 2 Вызов внешних действий (Внешние запросы API и т.д.)
-
-
-
вызвать запрос через внешние действия (при сохранении формы, отправке уведомления или других местах).
Ответ при вызове API, например, из формы, передается в поле Response из SELECT 1.
Туда можно передать полностью входную переменную @response без обработки, или результаты парсинга переменной @response в доступном для понимания виде.
CREATE PROCEDURE [dbo].[api_metrikaMonth_request]
@parameters ExtendedDictionaryParameter READONLY, -- входящие параметры для внутренней обработки (используйте Key, Value2)
@username nvarchar(32) -- текущий пользователь.
AS
BEGIN
declare @metrikaID nvarchar(256)
set @metrikaID = '53312170' -- Falcon
--set @metrikaID = '60713749' -- DEMO
declare @date1 nvarchar(256) = convert(nvarchar(10), dateadd(day, -30, getdate()), 120) --2020-04-26
declare @date2 nvarchar(256) = convert(nvarchar(10), getdate(), 120)
declare @token nvarchar(256) = 'token...'
declare @url nvarchar(512) = 'https://api-metrika.yandex.net/stat/v1/data/bytime?'
+ 'id='+@metrikaID
+ '&preset=sources_summary'
+ '&group=day'
+ '&metrics=ym:s:users,ym:s:visits,ym:s:manPercentage,ym:s:womanPercentage' +
+ '&date1=' + @date1 --2020-04-26
+ '&date2=' + @date2 -- 2020-04-26
-- SELECT 1 Msg, Result, Url (адрес, куда будет идти запрос)
select '' Msg, 1 Result, @url Url
-- SELECT 2 PARAMETERS - параметры, которые будут передаваться во внешний источник
-- select 'Content-type' name, 'application/json' value, 'header' [type] -- form (в форме передается), header (в http headers), get запросы передавайте прямо в URL
-- union
-- select 'Accept' name, 'application/json' value, 'header' [type]
--union
select 'Authorization' name, 'OAuth '+ @token value, 'header' [type]
END
CREATE PROCEDURE [dbo].[api_metrikaMonth_response]
@response nvarchar(max),
@parameters ExtendedDictionaryParameter READONLY, -- входящие параметры для внутренней обработки (используйте Key, Value2 - те же что и на request)
@username nvarchar(32)
AS
BEGIN
-- SELECT 1
select '' Msg, 1 Result, @response Response
-- SELECT 2 Внешние действия
END
Как отправить исходящий запрос POST с JSON телом?
Для этого указываем тип запроса POST и передаем в процедуре Request в SELECT 2 только 1 параметр с type=json и value =тело запроса в формате строки с JSON.
Примечание:
Учитывайте длину кодов и ключей (не должны быть больше 32 символов).
Работа с JSON в SQL Server
- https://docs.microsoft.com/ru-ru/sql/relational-databases/json/json-data-sql-server?view=sql-server-ver15
- https://stackoverflow.com/questions/2867501/parse-json-in-tsql
- https://habr.com/ru/post/343062/
- https://habr.com/ru/post/317166/
Работа с XML в SQL Server
- https://stackoverflow.com/questions/15680259/parse-xml-in-sql-server/15681388
- https://stackoverflow.com/questions/3989395/convert-xml-to-table-sql-server
Онлайн редакторы для XML и JSON
Инструменты позволяют скопировать большой текст и просматривать через дерево элементов.
- https://xmlgrid.net/ - просмотр XML
- https://jsoneditoronline.org/ - редактор JSON
Функции, полезные для API
В SQL есть набор полезных функций, которые выполняют стандартные преобразования
as_md5 - генерирует хеш строку MD5. Пример: dbo.as_md5('123')
as_hmac - генерирует хеш код в SHA1 и других форматах (https://ru.wikipedia.org/wiki/HMAC). Пример:
select dbo.as_hmac('SHA1', convert(varbinary(max), @secret),
convert(varbinary(max), @data ))
Важно, чтобы @secret и @data были varchar(max), а не nvarchar(max)
as_strToBase64 - генерирует значение в кодировке base64. Если на входе varbinary(max), то преобразуем специальным образом:
select dbo.as_strToBase64(lower(convert(nvarchar(max), @sh1, 2)))
as_NCharToUTF8Binary - преобразуем строку nvarchar в binary(max).
fn_PBKDF2 - стандарт формирования ключа на основе пароля. https://ru.wikipedia.org/wiki/PBKDF2
На практике возникает множество нюансов и возвращаемые функции могут давать не совсем тот результат - это зависит от формата входных данных (varbinary, nvarchar или varchar, lower or not). Проверяйте промежуточные тестовые данные через онлайн сервисы:
HMAC Service https://freeformatter.com/hmac-generator.html#ad-output
MD5 Online https://decodeit.ru/md5/
Base64 Online https://decodeit.ru/base64/
Google поиск по нашей документации
- Руководства
- Основа Falcon Space
- Основные компоненты
- Возможности
- Коммуникация с пользователем
- Дизайн, стилизация
- API, Интеграции Создание сервиса API для сайта. Программный интерфейс веб-платформы Как сделать вебхук (webhook) Прием платежей через Яндекс.Кассу Онлайн-платежи. Интеграция с Робокассой (платежный шлюз) Zapier интеграция на платформе Falcon Space Интеграция API DaData.ru подсказки по адресам Интеграция коллтрекинга МАНГО ОФИС (режим Площадка) Интеграция API Курсы валют Центрального Банка РФ в веб-платформе Falcon Space Интеграция API Почта РФ Интеграция API Служба доставки СДЭК (CDEK) Интеграция API Служба доставки Деловые линии Интеграция API IpGeoBase Город по IP-адресу Интеграция импорт и парсинг файла CSV Интеграция API DaData.ru Город по IP-адресу Как вычислить расстояние между 2 точками с координатами через Google Maps Передача файлов по FTP Сканирование штрихкодов и QR кодов через камеру и с картинок Получение данных контрагента по ИНН Прием платежей на сайте через CloudPayments Программное взаимодействие через API между 2 разными экземплярами Falcon Как сделать интеграцию с Мой Склад Внедрение подсказок dadata на сайт Вывод точек на карте Яндекс. Интеграция с Яндекс Карты Интеграция с телефонией Zadarma.com Как передать скрытый параметр при исходящем запросе из Request процедуры в Response Получение данных о контрагенте - интеграция с сервисом ЗаЧестныйБизнес Интеграция с AMO CRM Как импортировать данные в базу CRM из Google Контакты Вход/регистрация через ВКонтакте(vk.com) Интеграция CRM с онлайн чатом на сайте (Replain) Загрузка на форме текстовых файлов и обработка их в процедуре SaveItem Как связать yandex metrika clientID с пользователем на сайте и посмотреть полный путь его по сайту? Входящий API. Как учесть в отклике результат внешних действий в API
- Каталоги
- Навигация
- Документы
- Дополнительные компоненты
- Продвижение, SEO
- Системные моменты
- HOWTO
- HOWTO Таблицы
- HOWTO Формы
- Работа с SQL
- HOWTO JS
- HOWTO Верстка
- Решение проблем
Falcon Space
Это снижение стоимости владения
за счет меньшего количества людей для поддержки и узкого стека разработки. Про снижение стоимости владения продуктом
Это быстрое внесение изменений
по ходу эксплуатации программы. Как создается функционал на платформе
Это простой удобный интерфейс
адаптация под мобильные устройства. Про юзабилити платформы