README

ApiSutra

Декларативный SDK для создания API-клиентов

ApiSutra — PHP-пакет для создания SDK внешних API. Вы описываете операции, DTO и правила протокола, а пакет выполняет запросы, преобразует ответы и управляет авторизацией, повторными попытками и пагинацией. Приложение получает клиент с понятными операциями, типизированными данными и общей обработкой ошибок.

Нужны PHP 8.4+ и Composer. Ядро работает без приложения Laravel; для Laravel предусмотрена отдельная интеграция.

Возможности

Область	Что поддерживается
Конфигурация клиента	Настройки клиента и отдельных вызовов. Параметры ClientConfig, настройка аутентификации, учётные данные, обновление токенов, копии конфигурации, опции запроса, подключение контейнера
Операции SDK	Организация API в удобный клиент. Запросы, ресурсы, версии сервисов, поиск клиента, мультисервисные SDK
Транспорт	Выбор HTTP-клиента и режима ответа. Контракт транспорта, promise API, форматы ответа, внешние и подписанные URL
DTO	Типизированные модели данных. Атрибутные модели, обычные PHP-классы, внешние правила, типизированные коллекции
Гидратация DTO	Контроль формы и содержимого данных. Маппинг и профили, строгие типы, null и defaults, вложенные структуры, варианты элементов списка, неизвестные поля
Атрибуты	Декларации рядом с кодом. HTTP, параметры запроса, DTO, ответы, поведение, хуки
Валидация	Проверка входных данных до отправки. Правила запросов и DTO, подключение валидатора, oneOf и discriminator для body
Сериализация	Подготовка данных для HTTP. Части запроса, URI и query, тело запроса, даты и enum, касты, исключение служебного поля DTO
Результаты и ошибки	Общий способ работы с ответами. Типизированные результаты, ошибки и исключения, контекст ошибок
Диагностика	Поиск причин неожиданного поведения. Логи, traceId, debug-снимки, маскирование данных, пути ошибок DTO
Авторизация	Доступ к защищённым API. Стратегии, credentials, обновление токенов
Управление отправкой	Контроль нагрузки и времени выполнения. Повторные попытки, квоты, дедлайны, кеширование
Несколько запросов	Выполнение связанных и массовых операций. Пагинация, batch и pool, композиция и зависимости
Длительные операции	Получение отложенного результата API. Критерий готовности, режимы операции, ожидание и polling
Файлы	Потоковая передача файлов и работа с архивами. Загрузка multipart/binary и Base64 в JSON, скачивание в файл или поток, файловые поля DTO, чтение и распаковка архивов, запускаемый пример
Расширения	Подключение собственного поведения. Хуки, обработчики ответов, модули расширений, контекст вложенной гидратации
Каталоги SDK	Описание операций и типов для инструментов. Инвентаризация операций, каталог DTO ответов, справочники провайдера
Тестирование SDK	Проверка сценариев и контрактов API. Mock-ответы, фикстуры, live-проверки
Интеграции	Подключение к окружению приложения. Standalone, Laravel, Redis для общих квот

Как выглядит SDK

Импорты в обзорных фрагментах опущены:

Декларация запроса

GetRecordRequest задаёт операцию API:

// HTTP-метод и адрес операции.
#[Get('/records/{id}')]
// Повторы при временных ошибках API: до 3 попыток, включая первую.
#[Retry(attempts: 3)]
// Преобразовать содержимое поля data в типизированный DTO.
#[Returns(GetRecordResponseDto::class, unwrap: 'data')]
final class GetRecordRequest extends AbstractRequest
{
    public function __construct(
        // Подставить id в {id} адреса запроса.
        #[Path]
        public int $id,
    ) {
    }
}

Декларация ответа (DTO)

GetRecordResponseDto описывает данные, которые получит приложение:

// Типизированная модель записи, которую получит приложение.
final readonly class GetRecordResponseDto extends AbstractResponseDto
{
    public function __construct(

        #[From('record_id', fallback: ['id'])] // Если record_id отсутствует, взять id.
        public int $id,

        public string $title,

        // Преобразовать строку created_at из ответа API в объект даты.
        #[From('created_at')]
        #[DateTimeFrom(format: DATE_ATOM)]
        public DateTimeImmutable $createdAt,

        #[From('author.name')] // Прочитать имя из вложенного объекта author.
        public ?string $authorName = null,

        #[EmptyStringAsNull(blank: true)] // Пустую строку и пробелы превратить в null.
        public ?string $description = null,

        // Сохранить неизвестные поля ответа; в запросы клиента они не попадут.
        #[Extras]
        public array $_extra = [],
    ) {
    }
}

_extra — необязательное объявленное свойство: #[Extras] сохраняет в нём непрочитанные поля. Если они не нужны, уберите свойство вместе с атрибутом.

Возможности DTO на одном примере — вложенные модели, коллекции, enum, casts, defaults, исходящий JSON и ошибки.

Создание и конфигурирование клиента

Задайте общую политику DTO к клиенту:

$hydration = new HydrationConfig(policy: new RulePolicy(scalars: ScalarPolicy::Strict));

$client = new DemoClient(
    new ClientConfig(
        baseUrl: 'https://api.example.test',
        timeout: 15, // Таймаут HTTP-запроса в секундах.
        hydration: $hydration,
    ),
    HttpTransport::createDefault(),
);

/** @var GetRecordResponseDto $record */
$record = $client->records()->get(7)->send()->dataOrFail();
echo $record->createdAt->format('d.m.Y'); // 15.09.2026

$record — типизированный GetRecordResponseDto. dataOrFail() возвращает DTO или выбрасывает исключение; доступна и явная проверка результата.

Возможности конфигурирования клиента · Подключить свой API.

Установка и первый запуск

Пакет находится на стадии alpha. Установите его и запустите учебный SDK без ключей API и сетевых запросов:

composer require "brahmic/apisutra:^0.2@alpha"
php vendor/brahmic/apisutra/docs/example/sdk/run.php

Быстрый старт объясняет пример и переход к своему API.

Документация

Создать SDK — от анализа API до проверенной операции и покрытия.
Использовать готовый SDK — подключение к приложению и работа с результатами.
Справочник — настройки, контракты, приоритеты и ограничения.
Примеры — готовый код для локального запуска.

Все разделы и задачи · Передать задачу ИИ-агенту.

Разработка ApiSutra

Точка входа разработчика ApiSutra задаёт общий маршрут для человека и ИИ: окружение, архитектура, устройство пакета и проверка изменений. Подготовка вклада — в CONTRIBUTING.

Версии и лицензия

История изменений · Миграция · Лицензия MIT.

brahmic / apisutra

Package info

Security

Statistics