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

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