Canary Release for API Version Management: Concepts and ING Case Study

One of the biggest difficulties API providers face is managing versions and builds across instances; continuous iteration demands a version‑control approach that balances organizational needs, yet traditional versioning has drawbacks.

Why API Version Control and Canary Releases Matter

API providers often want to introduce new features quickly, while API consumers prefer stability; this tension makes version control contentious, and Roy Fielding famously argued against it.

What Is a Version?

Versioning creates distinct, independent releases of an API, typically progressing from beta to candidate to final versions, but this can lead to compatibility problems and fragmented user bases.

What Is a Canary Release?

A canary release mitigates risk by gradually exposing a small subset of users to a new version, similar to how a canary in a coal mine signals unsafe conditions; successful canaries become the default, and rollbacks are simple by stopping traffic to the new instances.

ING Bank’s Canary Release Workflow

At ING, most API interactions are driven by an API gateway that separates external and internal networks; services are discovered via a manifest linking endpoints and instances, and subscriptions bind applications to specific API versions.

The deployment process starts with API definitions in a Swagger file, registers services and manifests, and when a service instance starts, it reports its address and endpoint list to the discovery module.

As the canary is validated, traffic is shifted from old instances to the new ones until 100% of users are on the updated version, after which the old instances are retired.

Conclusion: Canary releases simplify version management for APIs that evolve rapidly, making them valuable across industries such as open banking, where they enable transparent, incremental upgrades without disrupting users.