docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/rest-bundle/requests.md
new file +80
ā0
1
+
# Request parameters
2
+
3
+
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](/docs/api/json-rpc-bundle/add_rpc_service/params), [`#[RPC\Assertions]`](/docs/api/json-rpc-bundle/add_rpc_service/assertions).
4
+
5
+
## Parameter sources
6
+
7
+
Sources are merged in this order; a later key overrides an earlier one:
8
+
9
+
1. route path variables;
10
+
2. query string;
11
+
3. form fields (`application/x-www-form-urlencoded`, `multipart/form-data`);
12
+
4. JSON body.
13
+
14
+
```
15
+
PUT /rest/catalog/items/42?title=query
16
+
Content-Type: application/json
17
+
18
+
{"title": "Book"}
19
+
```
20
+
21
+
calls `catalog.update` with `{"id": 42, "title": "Book"}` (for `int $id`).
22
+
23
+
Rules:
24
+
25
+
* An empty body means no parameters from the body.
26
+
* With a form `Content-Type` the body is not parsed as JSON.
27
+
* 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`.
28
+
* 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`.
29
+
30
+
Pass arrays, objects and DTOs in the JSON body.
31
+
32
+
## Type casting
33
+
34
+
:::info
35
+
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.
36
+
:::
37
+
38
+
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.
39
+
40
+
| Parameter type | Cast | Stays a string |
41
+
| --- | --- | --- |
42
+
| `string`, `mixed`, a union with `string` (`int\|string`) | never: a string is valid | |
43
+
| nullable (`?int`, `?bool`, `int\|null`) | `""` ā `null` | |
44
+
| `int` | an integer literal: `42`, `-7`, `0` | `007`, `+1`, ` 1`, `1.5`, out of `int` range |
45
+
| `float` | a numeric string: `1.5`, `2`, `1e3` | `1,5` |
46
+
| `int\|float` | `2` ā `2`, `2.5` ā `2.5` | |
47
+
| `bool` | `true`, `1` ā `true`; `false`, `0` ā `false` (case-insensitive) | `yes`, `on`, `""` |
48
+
| enum, `array`, class | never | |
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
+
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.
56
+
57
+
:::warning
58
+
The RPC core does not convert enum parameters from a string, neither in REST nor in JSON-RPC. See [Open issues](/docs/api/rest-bundle/developers/known_issues/open).
59
+
:::
60
+
61
+
## Response
62
+
63
+
* **Success**: status `200`, `Content-Type: application/json`, the body is the method result without the JSON-RPC envelope.
64
+
* **Error**: the HTTP status of the error and an RFC 9457 document; see [Error handling](/docs/api/rest-bundle/error_handling).
65
+
66
+
## What works from the RPC core
67
+
68
+
A REST call is executed through the JsonRpcBundle `RpcExecutor` (since 1.3), so the following apply to it:
69
+
70
+
* parameter conversion, default values, `#[RPC\Assertions]` and DTO validation;
71
+
* response caching with [`#[RPC\Cache]`](/docs/api/json-rpc-bundle/add_rpc_service/cache) and `#[RPC\CacheRelation]` invalidation (on `rpc.post_response`);
72
+
* [`#[RPC\Lock]`](/docs/api/json-rpc-bundle/add_rpc_service/lock);
73
+
* the application's `rpc.*` [event](/docs/api/json-rpc-bundle/functionality/events) listeners;
74
+
* `#[Autowire]` in method arguments.
75
+
76
+
Batch, notifications and `$rpc.callback` are not available via REST.
77
+
78
+
:::info
79
+
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.
80
+
:::