docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/functionality/versions.md
new file +60
ā0
1
+
# API versions
2
+
3
+
:::info
4
+
Available since version 10.0.
5
+
:::
6
+
7
+
Several versions of the same API can run at the same time: old clients call `/rpc`, new ones call `/rpc/v2`. A new version inherits all methods of the previous ones, can replace them with its own implementation and remove deprecated ones.
8
+
9
+
## How to declare a version
10
+
11
+
The version is set in the procedure class's [`#[RPC\Info]`](/docs/api/json-rpc-bundle/add_rpc_service/info): `version` is an integer (`1` by default, published as `v1`).
12
+
13
+
```php
14
+
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
15
+
use Ufo\RpcObject\RPC;
16
+
17
+
#[RPC\Info('user')] // v1
18
+
class UserApi implements IRpcService
19
+
{
20
+
public function get(int $id): array { /* ... */ }
21
+
public function legacySearch(string $q): array { /* ... */ }
22
+
}
23
+
24
+
#[RPC\Info('user', version: 2, removedMethods: ['legacySearch'])]
25
+
class UserApiV2 implements IRpcService
26
+
{
27
+
public function get(string $uuid): array { /* ... */ } // replaces user.get in v2
28
+
}
29
+
```
30
+
31
+
Rules:
32
+
33
+
* version N contains all methods of lower versions;
34
+
* a method with the same name in a newer class replaces the method of the previous version;
35
+
* `removedMethods` removes methods in this version (names without the class alias).
36
+
37
+
| Method | `v1` | `v2` |
38
+
| --- | --- | --- |
39
+
| `user.get` | `UserApi::get(int $id)` | `UserApiV2::get(string $uuid)` |
40
+
| `user.legacySearch` | `UserApi::legacySearch()` | ā |
41
+
42
+
## Entry points
43
+
44
+
| Entry point | Version |
45
+
| --- | --- |
46
+
| `POST /rpc`, `GET /rpc`, `GET /rpc/postman` | `v1` (default) |
47
+
| `POST /rpc/v2`, `GET /rpc/v2`, `GET /rpc/v2/postman` | `v2` |
48
+
| `bin/console ufo:rpc:process '<json>' --ver=v2` | `v2` |
49
+
50
+
Routes do not need to be registered separately: the versioned URLs are added by the same `config/router.yaml` import. Route names: `ufo_rpc_api_server` / `ufo_rpc_api_server_ver`, `ufo_rpc_api_postman` / `ufo_rpc_api_postman_ver` (with [API groups](/docs/api/json-rpc-bundle/functionality/groups), prefixed with the group).
51
+
52
+
A batch request to a versioned URL executes each item in that version. Async requests and notifications also respect the request version.
53
+
54
+
## Documentation
55
+
56
+
Each version has its own OpenRPC document and Postman collection. The document lists all registered versions in `info.x-versions`. Documentation protection (`protected_doc`) also applies to versioned URLs.
57
+
58
+
:::tip
59
+
Do not confuse the API version with `docs.project_version` in the [configuration](/docs/api/json-rpc-bundle/config): the latter is only a project version label in the documentation.
60
+
:::