Abills Developer
Child pages
  • Туториал по написанию API для ядра
Skip to end of metadata
Go to start of metadata

С 1.22.00.

За основу туториал по написанию API для модуля, здесь могут написаны только дополнительные подробности.

Местонахождение /lib/Abills/Api

Мы стараемся делить функционал ядра на микромодули, чтобы это было удобно логически делить, поддерживать.

Список микромодулей определено в функции _extra_api_modules в пэкэдже Paths.pm
А сами микромодули, находятся в Paths/.

Здесь собрано и ADMIN API так и USER API.

Название модуля обязательно определяется за префиксом, например /districts - файл должен называться Districts.pm, и соответственно создавать
пэкэдж Districts.
Исключение составляет User_core.pm.

За пример возьмём Fees.pm

Создание микромодуля

микророутер Fees 
# Обязательно Abills::Api::Paths::<module>
package Abills::Api::Paths::Fees;
=head NAME

  Fees api functions

=cut

use strict;
use warnings FATAL => 'all';

use Abills::Base qw(in_array);

# Конструктор микророутера
#**********************************************************
=head2 new($db, $conf, $admin, $lang)

=cut
#**********************************************************
sub new {
  my ($class, $db, $admin, $conf, $lang, $debug, $type) = @_;

  my $self = {
    db    => $db,
    admin => $admin,
    conf  => $conf,
    lang  => $lang,
    debug => $debug
  };

  bless($self, $class);

  $self->{routes_list} = ();

  if ($type eq 'admin') {
    $self->{routes_list} = $self->admins_routes();
  }
  elsif ($type eq 'user') {
    $self->{routes_list} = $self->user_routes();
  }

  return $self;
}

#**********************************************************
=head2 admin_routes() - Returns available ADMIN API paths
 
=cut
#**********************************************************
sub admin_routes {
  # Здесь нужно возвращать специальный массив ADMIN API
  return [];
}
 
#**********************************************************
=head2 user_routes() - Returns available USER API paths
 
=cut
#**********************************************************
sub user_routes {
  # Здесь нужно возвращать специальный массив USER API
  return [];
}


Словарь ошибок

В разработке.

Валидатор

Про валидацию

Микромодуль называется Fees, то нужно создавать Validations/Fees.pm.
Общие валидации находятся в Validations.pm, там могут быть кастомные, нужные вам валидации.

ADMIN API

Создание роутов и определение

путь /fees 
{
  # HTTP метод
  method      => 'DELETE',
  # Путь, обязательно начинается с имени микромодуля
  # определяем path_params 
  path        => '/fees/users/:uid/:id/',
  # Определение эндпоинта
  handler     => sub {
    my ($path_params, $query_params, $module_obj) = @_;
    # ...
  },
  # Загружаемый модуль.
  # Исторически функционал API делится по принципу Abills/mysql, так что мы можем немного сократить код.
  # Мы не особенно рекомендуем использовать эту опцию в будущем, но ознакомиться считаем нужно.
  module => 'Fees',
  # Определяем нужные параметры для авторизации.
  # ADMIN    - API_KEY
  # ADMINSID - admin_sid по cookie (в том числе для api_call)
  credentials => [
    'ADMIN', 'ADMINSID'
  ]
}

Написание OpenAPI

Про OpenAPI в ABillS

OpenAPI для ядра находится в корне misc/api/(admin|user)/[module]

Так что для работы нам нужно:

  • создать папку misc/api/user/fees
  • создать файл misc/api/user/fees/paths.yaml
  • создать папку misc/api/user/fees/paths
  • создать папку misc/api/user/fees/schemas

В остальном ничем не отличается от функционала в модулях.

Запускаем misc/api/generate_docs.pl и проверяйте bundle_admin.yaml

Поздравляем!

USER API

Создание роутов и определение

путь /user/fees 
{
  # HTTP метод
  method      => 'GET',
  # Путь, начинается в /user/ и названием микромодуля
  path        => '/user/fees/',
 # Определение эндпоинта
  handler     => sub {
    my ($path_params, $query_params, $module_obj) = @_;
    
    # ...
  },
  # Загружаемый модуль.
  # Исторически функционал API делится по принципу Abills/mysql, так что мы можем немного сократить код.
  # Мы не особенно рекомендуем использовать эту опцию в будущем, но ознакомиться считаем нужно. 
  module      => 'Fees',
  # Определяем нужные параметры для авторизации.
  # USER    - авторизация по header, полученном с /user/login
  # USERSID - авторизация по cookie (в том числе для api_call)
  # USERBOT - авторизация через наше API Bots
  # PUBLIC  - без авторизации
  # Тоесть, в данном случае путь может работать как и с авторизованными пользователями, так и нет.
  # Внутри хэндлера можно определять какой пользователь.
  credentials => [
    'USER', 'USERBOT'
  ]
},

Написание OpenAPI

Про OpenAPI в ABillS

OpenAPI для ядра находится в корне misc/api/(admin|user)/[module]

Так что для работы нам нужно:

  • создать папку misc/api/user/fees
  • создать файл misc/api/user/fees/paths.yaml
  • создать папку misc/api/user/fees/paths
  • создать папку misc/api/user/fees/schemas

В остальном ничем не отличается от функционала в модулях.

Запускаем misc/api/generate_docs.pl и проверяйте bundle_user.yaml

Поздравляем!

Практики

Повторяет с модулями.

Но ещё другие рекомендации относительно ядра

Разделение описания пути и реализации

На данный момент пока что не существует решения.

Использование пропса module

Поскольку API ядра делится практически за тем же принципом что и файлы Abills/mysql, то можно при создании роута и его определении сократить код с

обычное написание 
my $Fees = Fees->new($self->{db}, $self->{admin}, $self->{conf});
# ...

до:

пропс module
module => 'Fees',
  • No labels