When I first joined the OpenStack community a few years ago I had a very bad reaction when exposed to microversions. This had more to do with the implementation (which struck me as a very Not Invented Here solution) than their actual purpose in life. Over time I've become adapted to them and even on occasion have cause to recommend them as the correct solution in certain situations.

Many web API developers learn that the right thing to do is not change their API, or if they must change only do so in a backwards compatible fashion (meaning adding but never removing representation fields or URIs). For a service that is "owned" by a single deployment this can work well.

What about an API that:

• is accessed by all kinds of clients, with varying degrees of quality, flexibility and expertise
• must evolve (because of features, bugs, improving early suckiness)
• is hosted across multiple deployments around the world
• desire the same client code to work amongst multiple deployments at different releases

In that situation there can be no guarantee that all deployments present the same API. Microversions are a solution to those problems. They allow a client to declare "for this request I'm behaving as if the server is at version X.Y" and for the server to say "the client has asked me to behave as X.Y, for this request, so I will follow that code path".

The "this request" part is a critical aspect of the microversion solution. The other aspect is multiple deployments at different releases. Microversions aren't perfect, and may have limited applicability, but for APIs that have the needs described above, they are a tool worth considering.

Some related resources:

• Microversion Specification. Read this for details on how microversions actually work.
• Ensuring API Interoperability. Producing this document is what helped me understand the details of the value of microversions in the OpenStack environment.
• APIs as infrastructure: future-proofing Stripe with versioning. A blog posting that describes a solution used at Stripe that is quite similar to microversions.