API Versioning

[harlem88]

API versioning is crucial for managing changes without breaking user experiences.

• API versioning tracks changes to an API, allowing developers to add features or fix bugs without disrupting existing clients
• Common versioning methods: protobuf package, URI-based, header-based, and body-based
• Key benefits: maintains backward compatibility, enables new features, allows bug fixes, gives users control over upgrades

Quick comparison of versioning methods:

Method	How it works	Pros	Cons	Choice
Package	Different gRPC service to different client version	Simple to use		✔️
URI	Version in URL (e.g., /v1/users)	Simple to use	Clutters URLs	❌
Header	Version in HTTP headers	Keeps URLs clean	Trickier to implement	❌
Body	Version in request/response	Detailed control	More complex	❌

[joshuachp]

For a solution, we can version the package in the Probobuf definition.

This will generate different services that the Message Hub can implement to respond to the various client versions. This is the equivalent of adding the version in the URL.

Here is an example where it's implemented in tonic