re: Real World Developer's Problems: API Versioning VIEW POST


> REST doesn’t specify any method of versioning

The problem is that most of what we call RESTful API are not RESTful at all

A true RESTful API does not need versioning, as Fielding explains in this article


My point was that there is no need to anticipate such world-breaking changes with a version ID. We have the hostname for that. What you are creating is not a new version of the API, but a new system...

If you look at constraints of SemVer, a new version is basically that, a new system that doesn't try to be compatible with older clients.

If his point is "you do a new system, get a new hostname" the chain of arguments is simple.

  1. Do a new version
  2. Fielding says a new version is a new system
  3. Fielding says a new system needs a new hostname
  4. Put the version in the hostname

You missed the end of the sentence: "...but a new system with a new brand" :-)
It seems just a detail, but is fundamental, instead.

Fielding is not saying that a new version is a new system. He is talking about a totally different system, different just like and

The point is: when do you really need a new system when your API is true RESTful?

Read the sentence just after the one you mentioned:

On the Web, we call that a new website. Websites don’t come with version numbers attached because they never need to. Neither should a RESTful API. A RESTful API (done right) is just a website

Basically, a REST client should only know the entry URI of your (true) RESTful APIs. If you change the signature or the organization of your APIs, your client should be able to discover them without need to specify a version.

Indeed, in a true RESTful context, each resource must have the URIs of any related resources. Again, the client should know just the initial URI of your APIs. The other URIs must be dynamically discovered: basically this is the meaning of State Transfer in the REST acronym.

I didn't miss it, I deliberately omitted it, because it's only semantics. Different system or version is just a question of perspective here.

The only thing Fielding has to say about this problem: Either you never break backward compatibility or you are not doing REST. If you want to do REST, create a new API every time you would break backward compatibility.

He's only unhappy with the fact that some people call these new non-backward compatible systems "new major version" and not "new systems".

GTA isn't GTA3 etc.

code of conduct - report abuse