Request parameters

A REST request is turned into one RPC method call. Method parameters are collected from several sources and then processed by the RPC core the same way as JSON-RPC request parameters: default values, DTOs and type conversion, #[RPC\Assertions].

Parameter sources

Sources are merged in this order; a later key overrides an earlier one:

1. route path variables;
2. query string;
3. form fields (application/x-www-form-urlencoded, multipart/form-data);
4. JSON body.

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

{"title": "Book"}

calls catalog.update with {"id": 42, "title": "Book"} (for int $id).

Rules:

• An empty body means no parameters from the body.
• With a form Content-Type the body is not parsed as JSON.
• A body that is not valid JSON returns 400 with the detail Invalid JSON request body; JSON that is not an object or array (null, 42, "text") returns 400 with JSON request body must be an object or array.
• Service route values are not passed to the method: api_group, ver, rpcRoute, _rest_route, _rest_name_prefix, _rest_doc, _ver, _controller, _format, _locale, _stateless.

Pass arrays, objects and DTOs in the JSON body.

Type casting

Values from the path, query and form are always strings. Before merging, each of them is cast to the declared type of the method parameter with the same name. Values from the JSON body keep their JSON types and are not cast.

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

A value that cannot be cast stays a string, and the RPC core returns 400 with a type message in detail-data. Parameters that are not in the method signature are left unchanged.

Response

• Success: status 200, Content-Type: application/json, the body is the method result without the JSON-RPC envelope.
• Error: the HTTP status of the error and an RFC 9457 document; see Error handling.

What works from the RPC core

A REST call is executed through the JsonRpcBundle RpcExecutor (since 1.3), so the following apply to it:

• parameter conversion, default values, #[RPC\Assertions] and DTO validation;
• response caching with #[RPC\Cache] and #[RPC\CacheRelation] invalidation (on rpc.post_response);
• #[RPC\Lock];
• the application's rpc.* event listeners;
• #[Autowire] in method arguments.

Batch, notifications and $rpc.callback are not available via REST.