Request parameters

← Request parameters

Ashterix

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

en/docs/api/rest-bundle/requests.md new file +80 −0

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

Since version 1.3. In 1.0–1.2 values from the path, query and form stayed strings, and for int, float, bool parameters the RPC core returned a type error.

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.

Parameter type Cast Stays a string
string, mixed, a union with string (int|string) never: a string is valid
nullable (?int, ?bool, int|null) "" → null
int an integer literal: 42, -7, 0 007, +1, 1, 1.5, out of int range
float a numeric string: 1.5, 2, 1e3 1,5
int|float 2 → 2, 2.5 → 2.5
bool true, 1 → true; false, 0 → false (case-insensitive) yes, on, ""
enum, array, class never 
#[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.

The RPC core does not convert enum parameters from a string, neither in REST nor in JSON-RPC. See Open issues.

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.

Before 1.3 a REST call did not fire rpc.post_response, so #[RPC\CacheRelation] invalidation and post-response listeners did not run for REST.