Versioning

Reference

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.

Versioning

By 陳Ken

Versioning

  • 415