Версії API

← Версії API

Ashterix

docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api

uk/docs/api/json-rpc-bundle/functionality/versions.md новий файл +60 −0

Версії 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 у налаштуваннях: останній — лише підпис версії проєкту в документації.