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

Имя/пароль неверные

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

Falcon Space - функциональная веб-платформа разработки на узком стеке MS SQL/Bootstrap. Вводная по Falcon Space
Насколько полезной была статья?

Google поиск по нашей документации

Выгода от использования Falcon Space

В 2-3 раза экономнее и быстрее, чем заказная разработка
Более гибкая, чем коробочные решения и облачные сервисы
Используйте готовые решения и изменяйте под свои потребности
Нужна бесплатная консультация?
Получить оценку проекта
Создайте концепцию проекта на основе нашего шаблона и получите оценку проекта в виде КП.
Демо-сайт решений
Базисные решения, которые можно гибко адаптировать под себя: менять внешний вид, бизнес-логику и даже структуру базы данных.
Сайт использует Cookie. Правила конфиденциальности OK