Создание сервиса 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.

Как проходит основной процесс входящего запроса: 

1. Обращение извне по HTTPS GET к методу auth для получения token доступа (система проверяет логин, пароль и выдает токен, который будет проверяться в дальнейших обращениях). 
2. Отправка запроса action для выполнения некоего действия (Получить заказы, создать новый заказ). В рамках запроса происходит следующее:
   1. Проверяются права на выполнение операции
   2. Запускается хранимая процедура обработки действия, подготавливается ответ для вызывающей стороны в виде JSON, XML, Plain text.
   3. Выдается некий отклик на вызывающую сторону

Всегда лучше использовать коды для 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).

2. Вызываем метод API 

/api/action/getOrders?token=7285440B-BD32-405F-813D-C26DFED23DF5&catID=1

Передаем token, action (код метода) и произвольные параметры. 

1. в ExtendedDictionaryParameter @parameters используем Key, Value2, а не Key, Value!
2. в @parameters также передается содержимое самого запроса Request.InputStream (в Key=InputStream)
3. в @parameters также передается ключ remoteIP - IP вызывающей стороне (например, по нему можно проверить легитимность запроса к API)
4. Если используете для отправки метод POST, то обязательно указывайте   'content-type': 'application/x-www-form-urlencoded'. Проверять подобные запросы можно через программу postman.

Создание нового метода API

API создается следующим образом: 

1. Создается действие в таблице 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

Ответ при вызове 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

• 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/