docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/functionality/versions.md
новий файл +60
−0
1
+
# Версії API
2
+
3
+
:::info
4
+
Доступно з версії 10.0.
5
+
:::
6
+
7
+
Кілька версій одного API можуть працювати одночасно: старі клієнти викликають `/rpc`, нові — `/rpc/v2`. Нова версія успадковує всі методи попередніх, може замінювати їх власною реалізацією і прибирати застарілі.
8
+
9
+
## Як оголосити версію
10
+
11
+
Версія задається в [`#[RPC\Info]`](/docs/api/json-rpc-bundle/add_rpc_service/info) класу процедури: `version` — ціле число (за замовчуванням `1`, публікується як `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 { /* ... */ } // замінює user.get у v2
28
+
}
29
+
```
30
+
31
+
Правила:
32
+
33
+
* версія N містить усі методи нижчих версій;
34
+
* однойменний метод новішого класу замінює метод попередньої версії;
35
+
* `removedMethods` прибирає методи у цій версії (назви без псевдоніма класу).
36
+
37
+
| Метод | `v1` | `v2` |
38
+
| --- | --- | --- |
39
+
| `user.get` | `UserApi::get(int $id)` | `UserApiV2::get(string $uuid)` |
40
+
| `user.legacySearch` | `UserApi::legacySearch()` | — |
41
+
42
+
## Точки входу
43
+
44
+
| Точка входу | Версія |
45
+
| --- | --- |
46
+
| `POST /rpc`, `GET /rpc`, `GET /rpc/postman` | `v1` (за замовчуванням) |
47
+
| `POST /rpc/v2`, `GET /rpc/v2`, `GET /rpc/v2/postman` | `v2` |
48
+
| `bin/console ufo:rpc:process '<json>' --ver=v2` | `v2` |
49
+
50
+
Маршрути не треба реєструвати окремо: версійні адреси додає той самий імпорт `config/router.yaml`. Назви маршрутів: `ufo_rpc_api_server` / `ufo_rpc_api_server_ver`, `ufo_rpc_api_postman` / `ufo_rpc_api_postman_ver` (з [групами API](/docs/api/json-rpc-bundle/functionality/groups) — з префіксом групи).
51
+
52
+
Batch-запит на версійну адресу виконує кожен елемент у цій версії. Async-запити і notifications теж враховують версію запиту.
53
+
54
+
## Документація
55
+
56
+
Кожна версія має власний документ OpenRPC і колекцію Postman. Документ перелічує всі зареєстровані версії в `info.x-versions`. Захист документації (`protected_doc`) діє і для версійних адрес.
57
+
58
+
:::tip
59
+
Не плутайте версію API з `docs.project_version` у [налаштуваннях](/docs/api/json-rpc-bundle/config): останній — лише підпис версії проєкту в документації.
60
+
:::