docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/rest-bundle/developers/README.md
new file +63
ā0
1
+
# For developers
2
+
3
+
REST Bundle is an adapter over the [JsonRpcBundle](/docs/api/json-rpc-bundle/developers) core: it has no method map, validation or security of its own, it only turns an HTTP request into an RPC call and the result into a REST response. This section is for those who want to understand how it works inside or extend it.
4
+
5
+
## Principles
6
+
7
+
1. **The RPC method is the only implementation.** REST is one more transport for the same method: no REST controller per method, no second set of DTOs or separate validation.
8
+
2. **Explicit publishing.** A method appears in REST only with the Symfony `#[Route]` attribute. `#[RPC\IgnoreApi]` and `#[RPC\APIGroups]` work the same way as in RPC.
9
+
3. **Execution belongs to the RPC core.** The bundle builds an `RpcRequest` and executes it through `RpcExecutor`; parameter conversion, `#[RPC\Assertions]`, `#[RPC\Cache]`, `#[RPC\Lock]` and the `rpc.*` events behave as for a JSON-RPC call.
10
+
4. **Groups and versions come from the RPC service map.** Each API group and version has its own REST routes and documents; inherited and removed methods are defined by `#[RPC\Info(version:, removedMethods:)]`.
11
+
5. **HTTP semantics at the edge.** The REST layer is responsible only for what JSON-RPC lacks: paths, HTTP methods, statuses (`404`, `405`, `401`, ā¦) and the RFC 9457 error format.
12
+
6. **Documentation from the same metadata.** OpenAPI and Postman are generated from the service map, so they do not diverge from the code.
13
+
14
+
## Components
15
+
16
+
| Component | Role |
17
+
| --- | --- |
18
+
| `Services\RestServiceMap` | Reads the RPC service map of the current group and builds REST routes from `#[Route]` attributes (class + method) for each version |
19
+
| `Services\RpcRestRouteLoader` | Route loader of type `ufo_rest_api`: a route per method and version plus a `_method_not_allowed` fallback |
20
+
| `Routing\RestRouteImport` | Registers `config/router.yaml` with the JsonRpcBundle route loader (`IApiRouteImport`) |
21
+
| `EventDispatcher\RestControllerListener` | After routing, sets the group in `ApiGroupContext` and directs REST routes to the controller |
22
+
| `EventDispatcher\RestDocLocaleListener` | Documentation language from `Accept-Language` via `RpcLocaleNegotiator` |
23
+
| `Services\RestRequestParser` | Finds the route and RPC service, checks the HTTP method and token, creates the carrier |
24
+
| `Services\RpcFromRest` | Carrier (`IRpcHttpCarrier`): builds an `RpcRequest` from the path, query, form and body, casts strings to parameter types |
25
+
| `Controller\RestEntryPointController` | Executes the call through `RpcExecutor`, returns the result or a problem; serves OpenAPI and Postman |
26
+
| `Exceptions\RestErrorNormalizer`, `Rest*Exception` | Conversion of RPC errors to REST exceptions with HTTP statuses |
27
+
| `DocAdapters\Outputs\OpenApiAdapter`, `PostmanAdapter` | Build documents from `RestServiceMap` |
28
+
29
+
## Two phases
30
+
31
+
**Container and route compilation**
32
+
33
+
```
34
+
RPC procedures āāāŗ JsonRpcBundle ServiceMap (for each group and version)
35
+
ā
36
+
config/routes/*.yaml āāāŗ JsonRpcBundle loader āā RestRouteImport recognises config/router.yaml
37
+
ā sets the import's group, prefixes the names: <group>_<name>
38
+
ā¼
39
+
config/router.yaml
40
+
āā controller routes: documentation (/, /postman, /{ver}, /{ver}/postman), catch-all entry point
41
+
āā ufo_rest_api resource āāāŗ RpcRestRouteLoader āāāŗ RestServiceMap āāāŗ routes from #[Route]
42
+
```
43
+
44
+
**Request**: see [Lifecycle](/docs/api/rest-bundle/developers/lifecycle).
45
+
46
+
## What the bundle does not do
47
+
48
+
* It has no configuration tree of its own: everything is in `ufo_json_rpc`.
49
+
* It does not support batch, notifications and `$rpc.callback` via REST.
50
+
* It does not cache documents with `ETag`.
51
+
52
+
## In this section
53
+
54
+
* [Lifecycle](/docs/api/rest-bundle/developers/lifecycle): how a REST request passes through the bundle and the RPC core.
55
+
* [Extensions](/docs/api/rest-bundle/developers/extensions): events, replacing the parser, reading the REST map, other adapters.
56
+
* [Testing](/docs/api/rest-bundle/developers/testing): running and structure of the bundle's tests.
57
+
* [Known issues](/docs/api/rest-bundle/developers/known_issues/open): what does not work as expected and how to work around it.
58
+
59
+
General guidelines for core extensions are on the [JsonRpcBundle For developers](/docs/api/json-rpc-bundle/developers) page.
60
+
61
+
## Contributing
62
+
63
+
Found a bug or a mismatch with the documentation? Open an issue in the [bundle repository](https://github.com/UFO-Tech/rest-bundle/issues). For behaviour changes, add a functional test: routes, statuses, problem documents and documentation are the REST contract.