What is the benefit of versioning a REST api by date as Twilio does?

Question

Basically, I think it's a good idea to version your REST api. That's common sense. Usually you meet two approaches on how to do this:

• Either, you have a version identifier in your url, such as /api/v1/foo/bar,
• or, you use a header, such as Accept: vnd.myco+v1.

So far, so good. This is what almost all big companies do. Both approaches have their pros and cons, and lots of this stuff is discussed here.

Now I have seen an entirely different approach, at Twilio, as described here. They use a date:

At compilation time, the developer includes the timestamp of the application when the code was compiled. That timestamp goes in all the HTTP requests.

When the request comes into Twilio, they do a look up. Based on the timestamp they identify the API that was valid when this code was created and route accordingly.

It's a very clever and interesting approach, although I think it is a bit complex. It can be confusing to understand whether the timestamp is compilation time or the timestamp when the API was released, for example.

Now while I somehow find this quite clever as well, I wonder what the real benefits of this approach are. Of course, it means that you only have to document one version of your API (the current one), but on the other hand it makes traceability of what has changed more difficult.

Does anyone know what the advantages of this approach are, so why Twilio decided to do so?

Please note that I am aware that this question sounds as if the answer(s) are primarily opinion-based, but I guess that Twilio had a good technical reason to do so. So please do not close this question as primariliy opinion-based, as I hope that the answer is not.

Answer 1

Interesting question, +1, but from what I see they only have two versions: 2008-08-01 and 2010-04-01. So from my point of view that's just another way to spell v1 and v2 so I don't think there was a technical reason, just a preference.

This is all I could find on their decision: https://news.ycombinator.com/item?id=2857407

EDIT: make sure you read the comments below where @kelnos and @andes mention an advantage of using such an approach to version the API.

Answer 2

There's another thing I can think about that makes this an interesting approach is if you are the developer of such api.

You have 20 methods, and you need to introduce a breaking change in 1 of those.

Using semver (v1, v2, v3, etc) you need a v2 api. All your 20 methods now needs to respond to v2, but in reality, those methods aren't changed at all, aren't new.

Using dates, you can keep your unchanged methods as is, and when the request comes in, it just pick the best match.

I don't know how is this implemented, any information on that will be really welcome.