С 1.22.00.
В данной статье описано программный интерфейс всего API, как и со стороны модуля так и ядра, так и флоу.
Принцип работы и флоу
C самого начала, api.cgi проверяет ли включена опция на сваггер и ли это был вызов на OpenAPI
Если да - клиент получает bundle_user.yaml или bundle_admin.yaml в зависимости от реквеста.
Загружается центральный английский словарь, если это не выставлено конфигурацией API_CONF_LANGUAGE
Создаётся главный объект Abills::Api::Handle, в который записывается вся необходимая информация для полной изоляции контекста.
Вызывается api_call, с которого мы получаем ответ, статус, и Content-Type (по умолчанию application/json; charset=utf-8, если это не определено иначе)
Внутри api_call, с получаемым контекстом производится проверка, ли API_ENABLE включена.
Если нет - клиент получает ответ, что API отключено.
Проверяется данные авторизации ADMIN API
Создаётся объект Abills::Api::Router, в который помещают весь полученный контекст.
При инициализации, проверяется ли HTTP метод соответствует полученому (GET, POST, PATCH, PUT, DELETE)
Если нет - клиент получает ответ с HTTP статусом 405.
Дальше разбивается url на несколько сегментов по /
Система запоминает первый сегмент
Запоминает второй сегмент, но если этот сегмент число - система запоминает третий сегмент.
Создаётся объект Abills::Api::Paths, который приобретает частичный контекст.
Система проверяет,
если HTTP метод это GET, DELETE - то создаётся и присваивается query_params.
если есть Content-Type: multipart/form-data, то создаётся и присваивается query_params, ведь body уже обработано
если есть буфер, то система попытается его декодировать с помощью JSON.
если происходит ошибка декодирования - клиент получает ошибку декодирования и статус 400.
система сканирует query_params на предмет непозволительных символов, очищает буфер (для оптимизации памяти)
Дальше система проверяет первый сегмент URL - если это 'user', то попытается загрузить модуль или микромодуль как USER API на основе второго сегмента, и если загрузчик не определил модуль или микромодуль - система загружает User_core.pm
Если это не 'user' - загружает модуль или микромодуль как ADMIN API
Данный загрузчик позволяет значительно оптимизировать работу API, так как интерпретатору не приходится загружать несколько десятков файлов и проводить поиск по всем роутам.
Сам загрузчик получает с функции _extra_api_modules() названия микромодулей ядра, и смешивает с ними названия модулей.
Если префикса нет в этом списке - клиент получает 404.
На основе пришедших параметров (имя ресурса, 'user' или 'admin' api) попытается загрузить <module>::Api со всем заданным контекстом. Тоесть, первым приоритетом стоит название модуля.
Если загрузка успешная - создаёт объект и забирает список роутов.
Если нет - система попытается загрузить Abills::Api::Paths::<module>
если загрузка успешная - создаёт объект и забирает список роутов
если нет - клиент получает ошибку.
Список роутов определяется уже внутри объекта.
Изнутри объекта пробрасывается наружу словарь ошибок.
Если загружаемый модуль не оказался в списке модулей администратора - клиент получит 403.
Если загружаемого модуля не нашлось, система возвращает "остальные" системные пути на проверку.
После полной инициализации Abills::Api::Router система проверяет, ли есть за ним ошибка.
Если да - клиент получит ошибку от роутера, скорее всего 403 или 400.
В роутер иньектятся хуки на авторизацию (credentials).
Дальше вызывается функция handle, которая должна уже выполнить роут.
Но сначала внутри вызывается метод parse_request, который:
- Проверяет пришедший объект роута, если неправильный - переходит до следующего
- Парсит ключи внутри роута, подставляет их в path_params
- Проверяет опции на camelCase и придаёт им SCREAMING_UPPER_CASE
- Производит проверку формата
- Возвращает найденный путь, хэндлер (если он есть), path_params и query_params
Если роут не найден - клиент получает 404.
Если есть handler (старый метод) - запоминается.
На основе найденного пути производится вызов нужных хуков на авторизацию
Первый успешный хук позволяет системе пройти дальше.
Если хук на USER API - дополнительно в path_params присваивается uid.
Если нет успеха - клиент получает 401.
Если у роута есть схема валидации - система загрузит валидатор, и начнёт на основе данных производить проверку body.
Если проверка неуспешная - загружается словарь ошибок, процессится ошибка и возвращается клиенту, что схема не прошла по такой-то причине.
Система проверяет, если это ADMIN API, и в пути нужен uid, то система грузит модуль работы Users,
проверяет ли пользователь с таким uid существует.
Если нет - возвращается ошибка, что пользователя не существует.
Если есть - в path_params присваивается user_object.
Если есть у роута опция module (присуще для ядра), то система попытается его загрузить и присвоить как третий аргумент для хэндлера.
Если есть ошибка - клиент её получает.
Если у полученного роута есть опция controller и endpoint, то система попытается загрузить контроллер со всем наданным контекстом ПЛЮС встроенный словарь ошибок.
Загружаемый контроллер загружается с названием метода от опции endpoint
Если контроллера нет - загружается handler.
Хэндлер в пути запускается.
Если во время запуска случилась ошибка - клиент получает ошибку.
Если во время загрузки модуля ошибка - клиент получает ошибку.
Получаем конечный результат с хэндлера.
Присваиваем его роутеру.
Если результат пустой - присваивается пустой объект.
Система смотрит на полученный от роута content_type и присваивает его хэндлу.
Если авторизация успешная и хэндл успешный - система проверяет результат хэндлера, и старается удалить с него потенциально лишние данные.
Система на основе проверенных формирует JSON ответ.
Если включенно логирование - весь ответ и полученный реквест попадает в лог.
Клиент получает ответ сервера, статус и нужный content_type.
Объект пути
{
# HTTP метод, GET, POST, PUT, PATCH, DELETE
method => 'POST',
# Абсолютный путь, за которым можно будет достучаться, например billing.url/api.cgi/portal/articles
# для USER API обязательно должно начинаться с /user/*
# В пути определяются основные параметры, по типу :id, :uid, которое отобразятся в пути
path => '/portal/articles/',
# "Контроллер" для API /portal/articles/*
controller => 'Portal::Api::admin::Articles',
# Ссылка на функцию-эндпойнт контроллера
endpoint => \&Portal::Api::admin::Articles::post_portal_articles,
# Прямой хэндлер. Игнорируется, если присутствует controller и endpoint
handler => sub {
# $path_params - параметры с путей
# если USER API и авторизация - обязательно присутствует uid
# если ADMIN API и uid - обязательно присутствует user_object
# $query_params - параметры квери или боди
# если GET, DELETE - query параметры с URL
# иначе - body, form или JSON
# $module_obj - если присутствует опция module, то это объект дополнительного загружаемого модуль.
my ($path_params, $query_params, $module_obj) = @_
# ...
},
# Дополнительный загружаемый модуль. Может сократить повторяющийся код.
module => 'Fees',
credentials => [
# Параметры авторизации ADMIN API
# ADMIN - API_KEY
# ADMINSID - admin_sid по cookie (в том числе для api_call)
'ADMIN', 'ADMINSID'
# Параметры авторизации USER API
# USER - через header, полученном с /user/login
# USERSID - через cookie (в том числе для api_call)
# USERBOT - через API Bots
# PUBLIC - без авторизации
# Тоесть, в данном случае путь может работать как и с авторизованными пользователями, так и нет.
# Внутри хэндлера можно определять какой пользователь.
]
},
Контроллер
# Пэкэдэ <Module>::Api::(admin | user)::<Controller>
package Portal::Api::admin::Articles;
=head1 NAME
Portal articles manage
Endpoints:
/portal/articles/*
=cut
use strict;
use warnings FATAL => 'all';
# Словарь ошибок
use Control::Errors;
# Грузим нужные депенденси для этого контроллера
use Portal;
# Создаём объект словаря ошибок
my Control::Errors $Errors;
# Создаём объект(ы) депенденси
my Portal $Portal;
# Дополнительно: определяем permissions
my %permissions = ();
#**********************************************************
=head2 new($db, $admin, $conf)
=cut
#**********************************************************
sub new {
my ($class, $db, $admin, $conf, $attr) = @_;
my $self = {
db => $db,
admin => $admin,
conf => $conf,
attr => $attr
};
%permissions = %{$attr->{permissions} || {}};
bless($self, $class);
# Определяем депенденси
$Portal = Portal->new($db, $admin, $conf);
# Забираем "предустановленный" словарь ошибок
$Errors = $self->{attr}->{Errors};
return $self;
}
# И дальше пишем пути #
1;
Определение пути
#**********************************************************
=head2 delete_portal_articles_id($path_params, $query_params)
Endpoint DELETE /portal/articles/:id/
=cut
#**********************************************************
sub delete_portal_articles_id {
my $self = shift;
my ($path_params, $query_params) = @_;
# В $path_params находятся переменные которые определены путём
# Например, /portal/articles/:id/ будет иметь параметр $path_params->{id}
# в $query_params находятся параметры которые пришли с query
# например: /portal/articles/?title=test
# или c json/form body
# например: POST /portal/articles { "title": "test" }
my $list = $Portal->portal_articles_list({ ID => $path_params->{id}, COLS_NAME => 1 });
if (!($list && scalar(@$list))) {
# Пример пробрасывания ошибки
return $Errors->throw_error(1440002, { lang_vars => { ID => $path_params->{id} }});
}
my $result = $Portal->portal_article_del({ ID => $path_params->{id} });
if (!$Portal->{errno}) {
$Attachments->delete_attachment($path_params->{id});
}
# Стандартный результат при удалении, должен быть описан в Swagger
return $result;
}