This is part of a multi-part series on how to version your API.
In our last post we talked about using an integer to version your API. Today we are going to talk about a date.
When you are ready to cut a new version of your API, what if, instead of
incrementing an integer, we represented it with the date of the release, e.g.
2020-02-09?
There are a couple of obvious attractive properties of a date that make it viable as a version:
However, it seems to also play nicely with the philosophy of continuously rolling versions. Instead of major, irregular, painful upgrades, framing the evolution of your API as an ongoing process of manageable, bite-sized changes makes these changes less intimidating. And by representing those changes with a date, is is almost as if your are normalizing the progression of your API against the natural progression of time. Moreover, the distance between say 2020-02-09 and 2020-05-12 feels much smaller than the distance between v1 and v2 even if they represent the same diff.
Stripe has popularized this approach and it has worked well for them. They always maintain support for at least the previous version and communicate clearly about new versions coming online and old versions being deprecated.
The overall mentality is that an API is a "living" thing that will always evolve and therefore an integration with an API should be expected to evolve with it. But, that evolution is going to be manageable and ongoing.
This is the underlying reality of most APIs, in fact, but by setting the expectation up front with the client and by representing a changed version with a relative date rather than an absolute integer, the notion of change seems more manageable and normal.