Another interesting post by Steve. What are your thoughts on twilio's date prefix in the URI versus using "v1" for example? Does discovery appease the purists qualms about versioning? But if using HATEOS enables discovery (which twilio is doing), why put a date there in the first place? I am thinking they're future-proofing their top-level resource discovery, but maybe I'm missing something.
It's actually not future-proofing, in that today we have different version of the API: 2008-08-01 and 2010-04-01. Some sort of versioning is necessary so that we can improve our API without breaking current clients or forcing all of our users to update their code. And while the goal of a completely discoverable API is laudable, I've never seen it work well in practice. We have a real service with real users, and we need something that works well and is simple to consume.
And I don't see how date-based versioning is any better than version numbers from a HATEOS perspective, since it's not really any more discoverable. There is however an argument to be made that version numbers are simpler, clearer and easier to remember.
Isn't it simpler to infer backwards compatibility from proper major.minor version number bumps? A major version number bump indicates API(/ABI) breakage, plain and simple. A minor version bump is simply a backwards-compatible change to the existing major.
Version numbers for marketing purposes are not really that useful, but if they are strictly used to indicate compatibility, they are very helpful. No one cares if the API is at, say, version 1023.301 as long as they know that 1023.200 is compatible with the latest version and 1022.499 isn't.
We historically have not done version bumps for minor improvements to the API that do not break existing applications. 2010-04-01 has been updated a couple times since it was first released with new features (like subaccounts, applications and short codes) but all of those were additive there was no reason to change the version.
