Версії API

Доступно з версії 10.0.

Кілька версій одного API можуть працювати одночасно: старі клієнти викликають /rpc, нові — /rpc/v2. Нова версія успадковує всі методи попередніх, може замінювати їх власною реалізацією і прибирати застарілі.

Як оголосити версію

Версія задається в #[RPC\Info] класу процедури: version — ціле число (за замовчуванням 1, публікується як v1).

use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
use Ufo\RpcObject\RPC;

#[RPC\Info('user')]                       // v1
class UserApi implements IRpcService
{
    public function get(int $id): array { /* ... */ }
    public function legacySearch(string $q): array { /* ... */ }
}

#[RPC\Info('user', version: 2, removedMethods: ['legacySearch'])]
class UserApiV2 implements IRpcService
{
    public function get(string $uuid): array { /* ... */ }   // замінює user.get у v2
}

Правила:

версія N містить усі методи нижчих версій;
однойменний метод новішого класу замінює метод попередньої версії;
removedMethods прибирає методи у цій версії (назви без псевдоніма класу).

Метод	`v1`	`v2`
`user.get`	`UserApi::get(int $id)`	`UserApiV2::get(string $uuid)`
`user.legacySearch`	`UserApi::legacySearch()`	—

Точки входу

Точка входу	Версія
`POST /rpc`, `GET /rpc`, `GET /rpc/postman`	`v1` (за замовчуванням)
`POST /rpc/v2`, `GET /rpc/v2`, `GET /rpc/v2/postman`	`v2`
`bin/console ufo:rpc:process '<json>' --ver=v2`	`v2`

Маршрути не треба реєструвати окремо: версійні адреси додає той самий імпорт config/router.yaml. Назви маршрутів: ufo_rpc_api_server / ufo_rpc_api_server_ver, ufo_rpc_api_postman / ufo_rpc_api_postman_ver (з групами API — з префіксом групи).

Batch-запит на версійну адресу виконує кожен елемент у цій версії. Async-запити і notifications теж враховують версію запиту.

Документація

Кожна версія має власний документ OpenRPC і колекцію Postman. Документ перелічує всі зареєстровані версії в info.x-versions. Захист документації (protected_doc) діє і для версійних адрес.

Не плутайте версію API з docs.project_version у налаштуваннях: останній — лише підпис версії проєкту в документації.