Please check out Mike Amundsen’s Design and Build Great Web APIs so that you can draw technically exemplary REST examples which must be Hypermedia as the engine of application state (HATEOAS) in order to be RESTful, not merely and only CRUD. And certainly not versioning in any sense but given a label per component where change is presented in hypermedia. Why? Because it is exactly the reason why versioning is replaced with evolvability through HATEOAS that change and thus “versioning” is dealt with.

If you are defending and building out a versioned system and not a HATEOAS system, you are not talking about a RESTful system.

CRUD is a necessary condition to call an API "RESTful" but it is not sufficient. For an API to be called RESTful, it must afford CRUD, HATEOAS, H-Factor, self-description through HTTP OPTIONS[0] and SIMP[1].

Again, Fielding says:

“Unfortunately, versioning interface names only manages change for the API owner’s sake. That is a myopic view of interface design: one where the owner’s desire for control ignores the customer’s need for continuity.”

The creator of REST literally had a conference talk titled “API versioning: DON’T”. He’s that guy.

You cannot talk about how your article is providing a RESTful API with versioning when the inventor of REST says DO NOT VERSION (or, this is what I mean by it).

Use restconf, predecessor-version, latest-versino, etc. link relations: pass this with the resource as links in the JSON (using HAL, Siren, Hydra, Collection-JSON, etc.). https://www.iana.org/assignments/link-relations/link-relations.xhtml

Do NOT version the API, pass version information FOR THE RESOURCE which you can CORRELATE with versions of your API you have on the backend in the repo which you can tag. The customer does not really care about that information. The customer wants verion information FOR THE RESOURCE, NOT THE API.

The whole discussion about versioning is orthogonal to customer needs and even wants or desires. It’s funny devs always talk about getting things done when such a fundamental thing has been built into their systems (versioning the API), when it is the exact opposite of what customers want and need, and it is the exact opposite of REST and Roy Fielding’s goal.

[0]: http://zacstewart.com/2012/04/14/http-options-method.html

[1]: Safety-Idempotence-(Im)mutability-Presentation/Transclusion affordance guardance: https://www.w3.org/2011/10/integration-workshop/p/hypermedia-oriented-design.pdf

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store