docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/rest-bundle/requests.md
новий файл +80
−0
1
+
# Параметри запиту
2
+
3
+
REST-запит перетворюється на один виклик RPC-методу. Параметри методу збираються з кількох джерел і далі обробляються ядром RPC так само, як параметри JSON-RPC запиту: значення за замовчуванням, [DTO й конвертація типів](/docs/api/json-rpc-bundle/add_rpc_service/params), [`#[RPC\Assertions]`](/docs/api/json-rpc-bundle/add_rpc_service/assertions).
4
+
5
+
## Джерела параметрів
6
+
7
+
Джерела об'єднуються в такому порядку; пізніший ключ перекриває попередній:
8
+
9
+
1. змінні шляху маршруту;
10
+
2. query string;
11
+
3. поля форми (`application/x-www-form-urlencoded`, `multipart/form-data`);
12
+
4. JSON-тіло.
13
+
14
+
```
15
+
PUT /rest/catalog/items/42?title=query
16
+
Content-Type: application/json
17
+
18
+
{"title": "Book"}
19
+
```
20
+
21
+
викликає `catalog.update` з `{"id": 42, "title": "Book"}` (для `int $id`).
22
+
23
+
Правила:
24
+
25
+
* Порожнє тіло — параметрів з тіла немає.
26
+
* З `Content-Type` форми тіло не розбирається як JSON.
27
+
* Тіло, що не є коректним JSON, повертає `400` з `detail` `Invalid JSON request body`; JSON, що не є об'єктом чи масивом (`null`, `42`, `"text"`), — `400` з `JSON request body must be an object or array`.
28
+
* Службові значення маршруту не передаються в метод: `api_group`, `ver`, `rpcRoute`, `_rest_route`, `_rest_name_prefix`, `_rest_doc`, `_ver`, `_controller`, `_format`, `_locale`, `_stateless`.
29
+
30
+
Масиви, об'єкти й DTO передавайте в JSON-тілі.
31
+
32
+
## Приведення типів
33
+
34
+
:::info
35
+
З версії 1.3. У 1.0–1.2 значення зі шляху, query і форми лишались рядками, і для параметрів `int`, `float`, `bool` ядро RPC повертало помилку типу.
36
+
:::
37
+
38
+
Значення зі шляху, query і форми завжди рядки. Перед об'єднанням кожне з них приводиться до оголошеного типу параметра методу з тією самою назвою. Значення з JSON-тіла зберігають свої JSON-типи й не приводяться.
39
+
40
+
| Тип параметра | Приводиться | Лишається рядком |
41
+
| --- | --- | --- |
42
+
| `string`, `mixed`, union зі `string` (`int\|string`) | ніколи — рядок допустимий | |
43
+
| nullable (`?int`, `?bool`, `int\|null`) | `""` → `null` | |
44
+
| `int` | цілочисловий літерал: `42`, `-7`, `0` | `007`, `+1`, ` 1`, `1.5`, поза межами `int` |
45
+
| `float` | числовий рядок: `1.5`, `2`, `1e3` | `1,5` |
46
+
| `int\|float` | `2` → `2`, `2.5` → `2.5` | |
47
+
| `bool` | `true`, `1` → `true`; `false`, `0` → `false` (без урахування регістру) | `yes`, `on`, `""` |
48
+
| enum, `array`, клас | ніколи | |
49
+
50
+
```php
51
+
#[Route('/items/{id}', name: 'item', methods: ['GET'])]
52
+
public function item(int $id, bool $full = false): array {} // GET /rest/catalog/items/42?full=true
53
+
```
54
+
55
+
Значення, яке не вдалося привести, лишається рядком, і ядро RPC повертає `400` з повідомленням про тип у `detail-data`. Параметри, яких немає в сигнатурі методу, не змінюються.
56
+
57
+
:::warning
58
+
Параметри-enum ядро RPC не конвертує з рядка — ні в REST, ні в JSON-RPC. Див. [Актуальні помилки](/docs/api/rest-bundle/developers/known_issues/open).
59
+
:::
60
+
61
+
## Відповідь
62
+
63
+
* **Успіх** — статус `200`, `Content-Type: application/json`, тіло — результат методу без JSON-RPC обгортки.
64
+
* **Помилка** — HTTP-статус помилки і документ RFC 9457, див. [Обробка помилок](/docs/api/rest-bundle/error_handling).
65
+
66
+
## Що працює з ядра RPC
67
+
68
+
REST-виклик виконується через `RpcExecutor` JsonRpcBundle (з 1.3), тому для нього діють:
69
+
70
+
* конвертація параметрів, значення за замовчуванням, `#[RPC\Assertions]` і валідація DTO;
71
+
* кеш відповідей [`#[RPC\Cache]`](/docs/api/json-rpc-bundle/add_rpc_service/cache) та інвалідація `#[RPC\CacheRelation]` (на `rpc.post_response`);
72
+
* [`#[RPC\Lock]`](/docs/api/json-rpc-bundle/add_rpc_service/lock);
73
+
* лістенери [подій](/docs/api/json-rpc-bundle/functionality/events) `rpc.*` застосунку;
74
+
* `#[Autowire]` в аргументах методу.
75
+
76
+
Через REST недоступні batch, notifications і `$rpc.callback`.
77
+
78
+
:::info
79
+
До 1.3 REST-виклик не генерував `rpc.post_response`, тож інвалідація `#[RPC\CacheRelation]` і post-response лістенери для REST не спрацьовували.
80
+
:::