API versioning: stable integrations without risk to production

Last edited:

Anna Golubeva

—

June 1, 2025

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 versioning is used. We support several approaches to versioning, allowing integrators to use the desired 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 is convenient for the REST API
Accept header	Example: 'Accept: application/vnd. api+json; version = 2 '- separates data from version
GraphQL alias / versioned fields	Different versions via aliases: 'userV1', 'userV2' - convenient for gradual migration
Schema-level versions	Separate diagrams 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
Integration with banks, providers, B2B partners
Systems with long-lived mobile or IoT clients

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