API versions

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.

How to declare a version

The version is set in the procedure class's #[RPC\Info]: version is an integer (1 by default, published as 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 { /* ... */ }   // replaces user.get in v2
}

Rules:

• version N contains all methods of lower versions;
• a method with the same name in a newer class replaces the method of the previous version;
• removedMethods removes methods in this version (names without the class alias).

Entry points

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, prefixed with the group).

A batch request to a versioned URL executes each item in that version. Async requests and notifications also respect the request version.

Documentation

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.