Входящие запросы API (слой АПИ методов сайта)

Это слой API платформы, к которому обращается внешняя система через запросы GET/POST.

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

Обращение извне по HTTPS GET к методу auth для получения token доступа (система проверяет логин, пароль и выдает токен, который будет проверяться в дальнейших обращениях).
Отправка запроса 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).

Если данные корректные, то получим токен в отклике сервера. {"errorCode":0,"token":"7285440B-BD32-405F-813D-C26DFED23DF5","result":true,"msg":""}
Если есть ошибки, то result = false и errorCode содержит код ошибки.

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

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

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

Если все хорошо, то мы получаем result: true и в data содержатся выходные данные от результата выполнения метода.
Коды ошибок и описания к ним:

№	Код	Описание ошибки
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 - задает код действия (определят URL для метода API).

Оба эти параметра участвуют в формировании имени процедуры API. Код сущности определяет над каким объектом работаем, а код API задает действие, которое мы выполняем над этим объектом.

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 - Вызов внешних действий (уведомление на почту, телеграм и др.)

3.Вызываем метод как /api/action/actioncode1?token=token1&...{доп. параметры}....

Вызов 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

Страница-источник на сайте falconspace.ru