Ashterix 19.10.2026, 16:20

docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api

`uk/docs/api/rest-bundle/developers/README.md` новий файл +63 −0

Для розробників

REST Bundle — адаптер над ядром JsonRpcBundle: він не має власної карти методів, валідації чи безпеки, а лише перетворює HTTP-запит на RPC-виклик і результат — на REST-відповідь. Цей розділ — для тих, хто хоче зрозуміти, як він працює всередині, або розширити його.

Принципи

RPC-метод — єдина реалізація. REST — ще один транспорт для того самого методу: немає REST-контролера на кожен метод, другого набору DTO чи окремої валідації.
Публікація явна. Метод з'являється в REST лише з атрибутом Symfony #[Route]. #[RPC\IgnoreApi] і #[RPC\APIGroups] працюють так само, як у RPC.
Виконання належить ядру RPC. Бандл будує RpcRequest і виконує його через RpcExecutor; конвертація параметрів, #[RPC\Assertions], #[RPC\Cache], #[RPC\Lock] і події rpc.* поводяться як для JSON-RPC виклику.
Групи й версії — з RPC service map. Кожна група API і версія мають власні REST-маршрути та документи; успадковані й прибрані методи визначає #[RPC\Info(version:, removedMethods:)].
HTTP-семантика на межі. REST-шар відповідає лише за те, чого немає в JSON-RPC: шляхи, HTTP-методи, статуси (404, 405, 401, …) і формат помилок RFC 9457.
Документація з тих самих метаданих. OpenAPI і Postman генеруються з service map, тож не розходяться з кодом.

Компоненти

Компонент	Роль
`Services\RestServiceMap`	Читає RPC service map поточної групи й будує REST-маршрути з атрибутів `#[Route]` (клас + метод) для кожної версії
`Services\RpcRestRouteLoader`	Завантажувач маршрутів типу `ufo_rest_api`: маршрут на кожен метод і версію та запасний `_method_not_allowed`
`Routing\RestRouteImport`	Реєструє `config/router.yaml` у завантажувачі маршрутів JsonRpcBundle (`IApiRouteImport`)
`EventDispatcher\RestControllerListener`	Після роутингу встановлює групу в `ApiGroupContext` і спрямовує REST-маршрути в контролер
`EventDispatcher\RestDocLocaleListener`	Мова документації з `Accept-Language` через `RpcLocaleNegotiator`
`Services\RestRequestParser`	Знаходить маршрут і RPC-сервіс, перевіряє HTTP-метод і токен, створює carrier
`Services\RpcFromRest`	Carrier (`IRpcHttpCarrier`): будує `RpcRequest` зі шляху, query, форми й тіла, приводить рядки до типів параметрів
`Controller\RestEntryPointController`	Виконує виклик через `RpcExecutor`, повертає результат або problem; віддає OpenAPI і Postman
`Exceptions\RestErrorNormalizer`, `Rest*Exception`	Перетворення RPC-помилок на REST-винятки з HTTP-статусами
`DocAdapters\Outputs\OpenApiAdapter`, `PostmanAdapter`	Будують документи з `RestServiceMap`

Дві фази

Компіляція контейнера й маршрутів

RPC-процедури ──► ServiceMap JsonRpcBundle (для кожної групи й версії)
                        │
config/routes/*.yaml ──► завантажувач JsonRpcBundle ── RestRouteImport розпізнає config/router.yaml
                        │   встановлює групу імпорту, додає префікс до назв: <group>_<name>
                        ▼
              config/router.yaml
               ├─ маршрути контролера: документація (/, /postman, /{ver}, /{ver}/postman), загальний вхід
               └─ ресурс ufo_rest_api ──► RpcRestRouteLoader ──► RestServiceMap ──► маршрути з #[Route]

Запит — див. Життєвий цикл.

Чого бандл не робить

Не має власного дерева конфігурації: усе — в ufo_json_rpc.
Не підтримує через REST batch, notifications і $rpc.callback.
Не кешує документи з ETag.

Що є в розділі

Життєвий цикл — як REST-запит проходить через бандл і ядро RPC.
Розширення — події, заміна парсера, читання REST-мапи, інші адаптери.
Тестування — запуск і структура тестів бандла.
Відомі помилки — що працює не так, як очікується, і як це обійти.

Загальні положення для розширень ядра — на сторінці Для розробників JsonRpcBundle.

Співпраця

Знайшли помилку чи нестиковку з документацією — створіть issue в репозиторії бандла. Для змін у поведінці додавайте функціональний тест: маршрути, статуси, problem-документи й документація — це REST-контракт.