DataTerminology.comNEW
Also known as: Side-by-side Versioning
An API evolution strategy where multiple service versions run concurrently so clients can migrate at their own pace.
DESCRIPTION
The coexistence style keeps multiple API versions deployed simultaneously, allowing gradual client migration and minimizing breaking-change risk. It enables controlled deprecation windows and targeted routing by version. Operationally, it requires version-aware deployment, monitoring, and documentation, and may increase infrastructure costs. Strong governance is critical to prevent version sprawl and inconsistent behavior. It pairs well with blue-green and canary strategies to introduce new versions safely. Toolkits and gateways often provide routing and policy support for coexisting versions.
ALTERNATIVE DEFINITIONS
Microsoft Learn
You may need to support multiple versions of your API simultaneously.
Explicitly emphasizes parallel version support in API design.
Microsoft Learn
The API Versioning library allows you to maintain multiple versions of your APIs.
Highlights tooling support for running multiple API versions.
RELATED TERMS
API Versioning Schema Evolution Deprecation Policy Versioning Blue-Green Deployment Canary Release Contract Testing Consumer-Driven Contracts Microservices Continuous Delivery
COMPETING TERMS
Compatibility Style In-place Evolution
RELATIONS
- Broader: Versioning
KNOWLEDGE AREAS
Software Engineering Platform & Tooling Data Services
TARGET AUDIENCE
Software Architect Solution Architect Software Developer DevOps Engineer Product Owner IT Manager
EXTERNAL SOURCES
- Wikipedia - Application programming interface
- Microsoft Learn - API design best practices including versioning
- Zalando - Guidelines emphasizing compatibility
TOP QUESTIONS
When should I use the Coexistence Style for API versioning?
Use it when breaking changes are necessary but clients need time to migrate. It’s suitable for large ecosystems with diverse client release cycles.
Category: HowTo
What are the risks of the Coexistence Style?
Version sprawl, increased operational load, and inconsistent behavior across versions are key risks. Strong governance and deprecation policies mitigate them.
Category: Risks
How does Coexistence compare to Compatibility Style?
Coexistence runs multiple versions in parallel; compatibility aims to avoid breaking changes entirely. Many organizations blend both depending on change scope.
Category: Alternatives
What infrastructure is required for Coexistence Style?
You need routing based on version (path, header, or media type), separate deployments, monitoring per version, and clear documentation for consumers.
Category: Requirements
How do you deprecate versions under Coexistence?
Publish timelines, use deprecation headers, monitor usage, and provide migration guides. Enforce cutoffs after adequate notice and support windows.
Category: Management
What’s a common mistake with Coexistence Style?
Leaving versions active indefinitely without consolidation leads to maintenance burden. Plan convergence and automate removal of obsolete versions.
Category: Mistakes
How do feature flags relate to Coexistence?
Feature flags manage behavior within a version; coexistence manages multiple versions. They can be combined to reduce version proliferation.
Category: Opinion
How is testing handled across coexisting versions?
Use contract tests and distinct test suites per version. Track test coverage and SLIs per version to prevent regressions and drift.
Category: Testing
Where can I learn more about API versioning strategies?
Review vendor guidelines (Microsoft), community guidelines (Zalando), and API gateway documentation for routing and deprecation patterns.
Category: Learning