---

[I128-2830] Реестр API-контрактов и профилей внешней интеграции

---

НАЧАЛО >> Оглавление >> Общее описание >> История изменений >> Что нового в проекте I128 >> Версия 2026.3 >> [I128-2830] Реестр API-контрактов и профилей внешней интеграции📄 Скачать в DOCX

---

Тип	Версия	Статус	Приоритет	Исполнитель
⚙️ Новые возможности	2026.3	🔘 Завершено	Средний	Ilya Mikhaylenko

Компоненты: ИРБИС 128. Модуль API - API ИРБИС 64/128

Завершено: 08.09.2026 13:49

1. Цель

Нужно расширить существующий модуль API так, чтобы он стал владельцем реестра публичных API-контрактов и базовых профилей внешней интеграции ИРБИС 128.

Внешний потребитель должен получать стабильное машиночитаемое описание доступных методов и ресурсов, их версий, параметров, типов ответов, ошибок, прав, правил идемпотентности и диагностических признаков. Администратор должен иметь возможность видеть опубликованные API-контракты и создавать базовые integration adapter profiles без превращения предметных модулей в частные интеграционные прокладки.

1. Контекст

В системе уже есть модуль API, который является единой точкой JSON-RPC сервисов для внешних приложений. Сейчас он в основном вручную собирает методы, реализованные в Users, RQST, Bookland, EC и Database, а транспортные модули JSONRPC и REST занимаются приемом запросов и маршрутизацией.

Нужно развить этот существующий модуль, а не создавать новый системный APIмодуль. Доменные модули продолжают владеть своей бизнеслогикой и APIметодами, но API должен владеть опубликованным контрактом, версиями, правилами публикации, профилями интеграции и диагностикой APIповерхности.

1. Что Нужно Сделать

Нужно реализовать в модуле API реестр APIContract. Контракт должен иметь стабильный ключ, название, назначение, версию, статус публикации, список методов и ресурсов, supported transports, правила совместимости, deprecation policy, ссылку на Help и TestA-сценарии.

Нужно стандартизировать metadata для APIметодов, публикуемых доменными модулями через существующий паттерн __call/API. Для метода должны быть доступны stable key, название, описание, параметры, типы, обязательность, значения по умолчанию, схема ответа, коды ошибок, требования к правам, idempotency class, trace propagation и признак поддержки dryrun.

Нужно представить существующие JSON-RPC методы API как initial или legacy contract без изменения их текущего поведения. В этот контракт должны попасть методы работы с читателями, заказами, продлением, экземплярами, поиском, словарями и фасетами, если они уже публикуются через текущий API.

Нужно реализовать базовую модель IntegrationAdapterProfile. Профиль должен иметь стабильный ключ, название внешней системы или класса интеграции, направление обмена, ссылку на APIContract и версию, transport profile, service account или другой security subject, ссылки на секреты, mapping metadata, idempotency policy, external id policy, режим dry-run и диагностические признаки.

Нужно заложить поддержку mapping metadata без реализации полноценного двустороннего sync. Mapping должен ссылаться на стабильные field keys из FieldConfiguration, workflowстатусы и переходы из Workflow*, пользователей и организации через соответствующие resolverы, файлы через FT и secret references через Security/Secrets.

Нужно описать API-level idempotency contract для изменяющих операций: adapter profile, operation, object type, external id, fingerprint payload, TTL, результат повторного вызова, конфликт при другом fingerprint и связь с TraceContext.

Нужно добавить API diagnostics: contract version, adapter profile, method, subject, trace id, idempotency decision, результат проверки прав, безопасные details и ссылки на HealthCheck. Диагностика не должна раскрывать секреты, скрытые поля, закрытые записи и персональные данные без прав.

Нужно добавить HealthCheck provider для API: проверка опубликованных контрактов, доступности методов, корректности metadata, ссылок на transports, прав, secret references, mapping metadata, TestA coverage и устаревших deprecation-состояний.

Нужно подготовить TestAсценарии для экспорта APIContract, доступности legacy JSONRPC методов через published contract, проверки типов параметров, ошибок, прав, idempotency и отсутствия secret values в ответах, логах и diagnostics.

Нужно обновить Help модуля API: назначение API как владельца контрактов и profiles, отличие API от JSONRPC/REST, публикация contract, настройка adapter profile, idempotency, trace id, dry-run, диагностика и безопасная работа с секретами.

1. Границы Ответственности

API владеет APIконтрактами, версиями методов и ресурсов, integration adapter profiles, mapping metadata, external id contract, APIlevel idempotency, deprecation policy, dryrun APIопераций и API diagnostics.

JSONRPC и REST остаются transportслоями. Они принимают запросы, разбирают envelope или маршрут и передают вызов дальше, но не владеют контрактами, версиями, профилями интеграции и бизнесметодами.

EventBus остается владельцем событий, event log, inbox/outbox, webhook delivery, subscriptions, retry и dead-letter доставки. API может ссылаться на event contract, но не должен становиться event bus.

Queue остается владельцем фонового выполнения, worker runtime, scheduling, retry/backoff/timeout и job dead-letter. API может ставить или инициировать фоновые операции через общий контракт, но не исполняет queue runtime.

Security остается владельцем прав, grants/denies, ролей, field/view security, masking и audit доступа. API обязан вызывать Security, но не реализует собственный параллельный механизм прав.

Secrets хранятся только как ссылки на защищенные секреты. Значения секретов не должны попадать в API export, logs, diagnostics, events, TestA expected results или Help examples.

Доменные модули владеют бизнесоперациями, структурой своих записей, применением изменений и safe resolverами. API не должен знать внутреннюю модель Tasks, VirtualRef, RQST, Users, EC или других предметных модулей сверх опубликованного contract metadata.

В этот срез не входит полноценный bidirectional sync runtime, сложное conflict resolution, реализация конкретного Jira adapter, внешнего ticket-system adapter, почтового adapter или webhook adapter. Эти задачи должны заводиться отдельно после выбора внешнего потребителя и adapter profile.

1. Критерии Приемки

В модуле API есть реестр APIContract с версиями, статусами публикации, списком методов/ресурсов, supported transports и deprecation policy.

Существующие JSON-RPC методы API представлены в initial или legacy contract и продолжают работать совместимо со старой точкой JSONRPC.php?i128Module=API.

Доменные __call/API-методы могут отдавать стандартизированные metadata, достаточные для публикации метода в APIContract.

Администратор может увидеть API contracts, опубликованные методы, версии, статусы и базовые integration adapter profiles.

Базовый IntegrationAdapterProfile можно создать, проверить через HealthCheck и использовать как настройку для будущей интеграции без реализации конкретного внешнего adapter-а.

API-level idempotency для изменяющих операций описывает scope, fingerprint, TTL, повтор с тем же payload и конфликт при другом payload.

TraceContext проходит через API request и доступен в diagnostics.

Права на contract, profile, method, object, field и file проверяются через Security.

Secret values нигде не раскрываются через export, logs, diagnostics, events, Help или TestA.

JSONRPC и REST не получают новую ответственность за contract registry или integration profiles.

EventBus, Queue, Security, Secrets, FieldConfiguration, Workflow*, FT, Observability и доменные модули используются только через свои контракты.

HealthCheck показывает понятные ошибки битых методов, metadata, transport references, secret references, permission bindings, mapping metadata и TestA coverage.

TestA покрывает published contract export, legacy method compatibility, metadata validation, rights denial, idempotency repeat/conflict, trace propagation и отсутствие раскрытия секретов.

Help содержит руководство администратора и разработчика по контрактам API, adapter profiles, metadata __call/API, idempotency, trace id, diagnostics и границам с transport-модулями.

-

Реализован первый срез I128-2830 для существующего модуля API.

Что сделано:

• добавлен реестр APIContract с системным legacy JSONRPC контрактом api.legacyjsonrpc.v1;
• описаны metadata текущих JSON-RPC методов без изменения их поведения;
• добавлены схемы IntegrationAdapterProfile, idempotency policy и diagnostics;
• добавлены чтение recordbacked APIконтрактов/профилей, валидаторы и API/CheckHealth;
• включен административный список APIзаписей и briefформат;
• обновлены Help-разделы;
• добавлены saferead TestAпроверки.

Не входит в этот PR:

• runtime mapping/external ids (I128-2831);
• bidirectional sync/conflict resolution (I128-2832);
• конкретные внешние adapters.

Проверка:

• php -l по modules/API;
• git diff --check;
• TestA: API saferead + structural, 17/17 passed, runid 2026090506172266d96956.

1. Связанные задачи

1.1. 🔗 blocks: I128-2831

1.2. 🔗 blocks: I128-2832

1.3. 🔗 blocks: I128-2793

1.4. 🔗 blocks: I128-2794

1.5. 🔗 blocks: I128-2795

1.6. 🔗 blocks: I128-2797

1.7. 🔗 blocks: I128-2798

1.8. 🔗 blocks: I128-2799

1.9. 🔗 blocks: I128-2818

1.10. 🔗 blocks: I128-2825

1.11. 🔗 blocks: I128-2829