Параметри запиту

REST-запит перетворюється на один виклик RPC-методу. Параметри методу збираються з кількох джерел і далі обробляються ядром RPC так само, як параметри JSON-RPC запиту: значення за замовчуванням, DTO й конвертація типів, #[RPC\Assertions].

Джерела параметрів

Джерела об'єднуються в такому порядку; пізніший ключ перекриває попередній:

1. змінні шляху маршруту;
2. query string;
3. поля форми (application/x-www-form-urlencoded, multipart/form-data);
4. JSON-тіло.

PUT /rest/catalog/items/42?title=query
Content-Type: application/json

{"title": "Book"}

викликає catalog.update з {"id": 42, "title": "Book"} (для int $id).

Правила:

• Порожнє тіло — параметрів з тіла немає.
• З Content-Type форми тіло не розбирається як JSON.
• Тіло, що не є коректним JSON, повертає 400 з detail Invalid JSON request body; JSON, що не є об'єктом чи масивом (null, 42, "text"), — 400 з JSON request body must be an object or array.
• Службові значення маршруту не передаються в метод: api_group, ver, rpcRoute, _rest_route, _rest_name_prefix, _rest_doc, _ver, _controller, _format, _locale, _stateless.

Масиви, об'єкти й DTO передавайте в JSON-тілі.

Приведення типів

Значення зі шляху, query і форми завжди рядки. Перед об'єднанням кожне з них приводиться до оголошеного типу параметра методу з тією самою назвою. Значення з JSON-тіла зберігають свої JSON-типи й не приводяться.

#[Route('/items/{id}', name: 'item', methods: ['GET'])]
public function item(int $id, bool $full = false): array {}   // GET /rest/catalog/items/42?full=true

Значення, яке не вдалося привести, лишається рядком, і ядро RPC повертає 400 з повідомленням про тип у detail-data. Параметри, яких немає в сигнатурі методу, не змінюються.

Відповідь

• Успіх — статус 200, Content-Type: application/json, тіло — результат методу без JSON-RPC обгортки.
• Помилка — HTTP-статус помилки і документ RFC 9457, див. Обробка помилок.

Що працює з ядра RPC

REST-виклик виконується через RpcExecutor JsonRpcBundle (з 1.3), тому для нього діють:

• конвертація параметрів, значення за замовчуванням, #[RPC\Assertions] і валідація DTO;
• кеш відповідей #[RPC\Cache] та інвалідація #[RPC\CacheRelation] (на rpc.post_response);
• #[RPC\Lock];
• лістенери подій rpc.* застосунку;
• #[Autowire] в аргументах методу.

Через REST недоступні batch, notifications і $rpc.callback.