Versioning
Reference
- Creating, evolving, and versioning microservice APIs and contracts | Microsoft Docs
- Get to know 4 microservices versioning techniques
- The Ultimate Guide to Microservices Versioning Best Practices
- CanaryRelease
- Continuous integration - feature flags vs versioning for APIs - DevOps Stack Exchange
- Feature Flag Anti-Patterns: Flags to Manage API Versions - Split
- architecture - Microservice Versioning - Stack Overflow
Challenge
1. Micro-service Backend
2. Multiple FE apps ( Multiple Repos / Mono Repo / Monolith )
3. Multi-tenancy ? single-tenancy?
Concerns
1. Downward compatible (backwards compatibility)
2. Version alignment
3. Document / change logs
General Versioning Techniques
-
URI versioning
-
header versioning
-
semantic versioning
-
calendar versioning
Reduce Versioning Issues
1. Downward compatible (backwards compatibility)
2. Feature Flag
3. Version your APIs
Downward Incompatible
Remove or rename an endpoint.
Remove a field or type from the response.
Change an input parameter to required.
Add a new required input parameter.
How to prevent
URL path: “api.my-service.com/v1/catalog”
Path param: “api.my-service.com/catalog?version=1.2”
Accept header: Accept:application/catalog.v1+json
Custom header: My-Service-Version:2.3
Feature Flag
1. Shipping Incomplete Code To Production
2. Control Feature Release and Rollouts
3. Speed up How You Merge Into Your Main Branch
Deployment Practices and Versioning
Deployment Practices and Versioning
Canary deployments,
Blue-green deployments,
A/B testing deployments.
Some thoughts
you can mix and match of different stretagies
For Major changes you can use Routing based versioning
For other you can use Adapter Based Versioning
1. Internal Services have to go through Reverse Proxy for consumption.
2. Consumers always have to be aware of the required versioning.
Should you version the entire service or just the api?
1. The team just has to support one version of the service (bugs are just corrected once)
2. Less cognitive drain on the team for not having to understand tons of different and potentially very distinct versions of the service
3. Less resource consumption
4. Garantee that everything is consistent between versions (if not a garantee, at least it is much more probable)
Release notes
As a reminder, we only version backwards incompatible changes, so generally, you still get access to new features we release on the API without needing to upgrade. You can use different version headers for each request, so you can upgrade incrementally to get to the latest version.