Versioning API: `/v1/`, `Accept: version`, `GraphQL alias`

Versioning API: `/v1/`, `Accept: version`, `GraphQL alias`

As the API evolves, new methods, parameters, and logic emerge. In order not to disrupt the work of current clients, API replication is used. We support several approaches to versioning, allowing integrators to use the necessary version of the interface without risk for stable operation.

This is important both when scaling the platform and when implementing updates, testing or servicing old clients.

Versioning methods

Method	Description and Benefits
Version in URL ('/v1/')	The most understandable and popular way - convenient for REST API
Accept header	Example: 'Accept: application/vnd. api+json; version = 2 '- separates data from version
GraphQL alias/versioned fields	Different versions via alias: 'userV1', 'userV2' - convenient for gradual migration
Schema-level versions	Separate schemas and modules in OpenAPI/Swagger for each version

How implemented

API structure with '/v1/', '/v2/' and independent routes
Checking'Accept 'and'X-API-Version' headers
GraphQL supports aliases and versioned schemas ('userV1', 'userV2')
Ability to A/B test new versions without risk to production
Logging of calls to each version for analysis and migration

Business and Integrator Benefits

Support old customers without slowing down
Multi-Generation API Parallel Operation
Safely implement new features without breaking backwards compatibility
Flexibility to scale and upgrade infrastructure
Seamless migration between controlled and analytic versions

Where especially important

Platforms with multiple external clients
Projects with API-first approach and long lifecycle
Integrations with banks, providers, B2B partners
Systems with long-lived mobile or IoT clients

API versioning is the foundation of reliability and flexibility in integrations. Regardless of the format (REST, GraphQL or gRPC), we ensure the safe development of interfaces - without failures, conflicts and loss of compatibility.