11

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.

Community
  • 1
  • 1
Golo Roden
  • 140,679
  • 96
  • 298
  • 425

3 Answers3

3

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.

Bogdan
  • 23,890
  • 3
  • 69
  • 61
  • 5
    Yes, there are only two versions, but you can actually specify any date you want. Say I wrote an app today, and I don't remember the current version (date) number. So I just use today's date: 2014-12-23. The API will automatically pick the latest API version that's no newer than the date I specify. – kelnos Dec 24 '14 at 05:24
  • @kelnos: that works with a version number too. For example, you can have `/v1/api/` and `/v2/api/` but you also expose a `/api/` that points to the latest version, basically an alias for `/v2/api/` – Bogdan Dec 26 '14 at 18:19
  • 3
    @Bogdan, by exposing a default/latest version of the api, as you suggest with `/api/`, the client is at risk of accepting breaking changes, as latest might be v2, v3, etc. The date gives developers an easy way to request latest-as-of-today, and keeps them safe from breaking changes that might get introduced tomorrow. – andes Aug 19 '15 at 15:40
  • @andes: yes. User kelnos also mentioned the same thing, but I somehow missed the point. I'll change the answer to prompt users to read the comments too. – Bogdan Aug 29 '15 at 07:51
3

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.

Bart Calixto
  • 19,210
  • 11
  • 78
  • 114
2

I used to work for a company that used date versioning (as in each api call had param of the API date desired ?v=20200630) and loved it.

It lets you be less strict than with the traditional versioning (v1, v2, v3) as client developers don't need to even care about the version number and just use the current build time. Everything else is pretty much the same as as with the traditional versioning + small benefit from seeing date checks in the server code - you can easily see how old this or that code path is.

I believe the situation would have been different if we had to support a number of external clients and for example fix a bug in ?v=20200630 - there is no elegant way to specify something like ?v=20200630.1. As you can see from Twilio's experience they were just changing what API version 2010-04-01 was - thus client couldn't be sure which version exactly it was seeing.

So my outcome from this:

  • date based version seems easier and more flexible when you are a typical startup or a small company with a few of apps (e.g. frontend, iOS, Android) and no or few 3rd party clients. Date-based versioning makes it a bit easier for client developers to "just write code" and since you control all the code, most of the time you can fix old API bugs by just releasing a new version and asking clients to switch to it

  • Once you start having the real need to maintain the old API versions (AKA when you have a number of important clients who are not likely to update quickly), then semver versioning becomes more reliable

Artem
  • 776
  • 5
  • 18
  • This is still an indication that you don't have an API that truly supports REST but is just an RPC gateway, probably with external documentation (OpenAPI, Swagger, ...) and what not. The idea behind REST is that clients are decoupled from servers and that the representation exchanged is actually the thing they operate on. As long as both sides support the same media types they exchange "messages" for they are able to process these requests. The media type that defines the respective elements that may appear within a document as well as its semantics are actually the important part ... – Roman Vottner Jul 16 '21 at 13:26
  • ... and not what version the endpoint currently has. If a media type is lacking support of some needed features, i.e. like adding a deprecation warning on certain resource's fields, either a new media type should be defined that adds that capability or the current one needs to be refined to support that option. These is similar like to HTML is defined. It went through multiple "versions" already though it kept backwards compatible so that older versions are still processable. – Roman Vottner Jul 16 '21 at 13:31