docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/rest-bundle/developers/README.md
новий файл +63
−0
1
+
# Для розробників
2
+
3
+
REST Bundle — адаптер над ядром [JsonRpcBundle](/docs/api/json-rpc-bundle/developers): він не має власної карти методів, валідації чи безпеки, а лише перетворює HTTP-запит на RPC-виклик і результат — на REST-відповідь. Цей розділ — для тих, хто хоче зрозуміти, як він працює всередині, або розширити його.
4
+
5
+
## Принципи
6
+
7
+
1. **RPC-метод — єдина реалізація.** REST — ще один транспорт для того самого методу: немає REST-контролера на кожен метод, другого набору DTO чи окремої валідації.
8
+
2. **Публікація явна.** Метод з'являється в REST лише з атрибутом Symfony `#[Route]`. `#[RPC\IgnoreApi]` і `#[RPC\APIGroups]` працюють так само, як у RPC.
9
+
3. **Виконання належить ядру RPC.** Бандл будує `RpcRequest` і виконує його через `RpcExecutor`; конвертація параметрів, `#[RPC\Assertions]`, `#[RPC\Cache]`, `#[RPC\Lock]` і події `rpc.*` поводяться як для JSON-RPC виклику.
10
+
4. **Групи й версії — з RPC service map.** Кожна група API і версія мають власні REST-маршрути та документи; успадковані й прибрані методи визначає `#[RPC\Info(version:, removedMethods:)]`.
11
+
5. **HTTP-семантика на межі.** REST-шар відповідає лише за те, чого немає в JSON-RPC: шляхи, HTTP-методи, статуси (`404`, `405`, `401`, …) і формат помилок RFC 9457.
12
+
6. **Документація з тих самих метаданих.** OpenAPI і Postman генеруються з service map, тож не розходяться з кодом.
13
+
14
+
## Компоненти
15
+
16
+
| Компонент | Роль |
17
+
| --- | --- |
18
+
| `Services\RestServiceMap` | Читає RPC service map поточної групи й будує REST-маршрути з атрибутів `#[Route]` (клас + метод) для кожної версії |
19
+
| `Services\RpcRestRouteLoader` | Завантажувач маршрутів типу `ufo_rest_api`: маршрут на кожен метод і версію та запасний `_method_not_allowed` |
20
+
| `Routing\RestRouteImport` | Реєструє `config/router.yaml` у завантажувачі маршрутів JsonRpcBundle (`IApiRouteImport`) |
21
+
| `EventDispatcher\RestControllerListener` | Після роутингу встановлює групу в `ApiGroupContext` і спрямовує REST-маршрути в контролер |
22
+
| `EventDispatcher\RestDocLocaleListener` | Мова документації з `Accept-Language` через `RpcLocaleNegotiator` |
23
+
| `Services\RestRequestParser` | Знаходить маршрут і RPC-сервіс, перевіряє HTTP-метод і токен, створює carrier |
24
+
| `Services\RpcFromRest` | Carrier (`IRpcHttpCarrier`): будує `RpcRequest` зі шляху, query, форми й тіла, приводить рядки до типів параметрів |
25
+
| `Controller\RestEntryPointController` | Виконує виклик через `RpcExecutor`, повертає результат або problem; віддає OpenAPI і Postman |
26
+
| `Exceptions\RestErrorNormalizer`, `Rest*Exception` | Перетворення RPC-помилок на REST-винятки з HTTP-статусами |
27
+
| `DocAdapters\Outputs\OpenApiAdapter`, `PostmanAdapter` | Будують документи з `RestServiceMap` |
28
+
29
+
## Дві фази
30
+
31
+
**Компіляція контейнера й маршрутів**
32
+
33
+
```
34
+
RPC-процедури ──► ServiceMap JsonRpcBundle (для кожної групи й версії)
35
+
│
36
+
config/routes/*.yaml ──► завантажувач JsonRpcBundle ── RestRouteImport розпізнає config/router.yaml
37
+
│ встановлює групу імпорту, додає префікс до назв: <group>_<name>
38
+
▼
39
+
config/router.yaml
40
+
├─ маршрути контролера: документація (/, /postman, /{ver}, /{ver}/postman), загальний вхід
41
+
└─ ресурс ufo_rest_api ──► RpcRestRouteLoader ──► RestServiceMap ──► маршрути з #[Route]
42
+
```
43
+
44
+
**Запит** — див. [Життєвий цикл](/docs/api/rest-bundle/developers/lifecycle).
45
+
46
+
## Чого бандл не робить
47
+
48
+
* Не має власного дерева конфігурації: усе — в `ufo_json_rpc`.
49
+
* Не підтримує через REST batch, notifications і `$rpc.callback`.
50
+
* Не кешує документи з `ETag`.
51
+
52
+
## Що є в розділі
53
+
54
+
* [Життєвий цикл](/docs/api/rest-bundle/developers/lifecycle) — як REST-запит проходить через бандл і ядро RPC.
55
+
* [Розширення](/docs/api/rest-bundle/developers/extensions) — події, заміна парсера, читання REST-мапи, інші адаптери.
56
+
* [Тестування](/docs/api/rest-bundle/developers/testing) — запуск і структура тестів бандла.
57
+
* [Відомі помилки](/docs/api/rest-bundle/developers/known_issues/open) — що працює не так, як очікується, і як це обійти.
58
+
59
+
Загальні положення для розширень ядра — на сторінці [Для розробників JsonRpcBundle](/docs/api/json-rpc-bundle/developers).
60
+
61
+
## Співпраця
62
+
63
+
Знайшли помилку чи нестиковку з документацією — створіть issue в [репозиторії бандла](https://github.com/UFO-Tech/rest-bundle/issues). Для змін у поведінці додавайте функціональний тест: маршрути, статуси, problem-документи й документація — це REST-контракт.