This blog post is about my understanding of the versioning aspect of true RESTful APIs, or as I’m going to refer to them further, Hypermedia APIs, and how link context, and rel attribute in particular, lets you get away without versioning your API while keeping clients from breaking. The rest of this post is going to assume that you are familiar with Richardson Maturity Model and modern MVC frameworks like Symfony2 or Rails.

The routing component of such frameworks serves a double purpose:

• First and foremost, it lets framework users handle different URIs by routing them to various controller actions.
• Secondly, and what is more relevant to this blog post, routing lets framework users create route aliases and then use them to generate links in the view.

For example, if we defined a route called ‘home’ for URI ‘/’, we could then generate it in the view with something like:

1

<a href="<?php echo $router->generate("home"); ?>">Home</a>

This proves to be incredibly useful when you change the actual URIs of each route since you don’t have to modify the views later.

From the API design point of view, when links contain ‘rel’ attribute:

1

<link href="/" rel="home" />

Hypermedia clients don’t need to know about the actual URI for ‘home’ resource, hence that URI can be changed without the need of modifying the client, just like you won’t break your website by changing URIs of some controller actions when using a modern framework. Additionally, you don’t need to version your websites because the link to ‘home’ is now linking to ‘/index’ instead of ‘/’.

By the way, when designing websites, we provide context to our users by putting text ‘Home’ inside the ‘a’ tag in the website navigation, to let them know what the hyperlink is for and not where it is linking to, which changes less frequently:

1

<a href="/index">Home</a>

Say good bye to versioned “RESTful” APIs, and welcome discoverable hypermedia APIs!

Cheers!

P.S. You could even use your real route names, the ones you define in your favorite framework, as values for ‘rel’ attributes of your links. Additionally, to make ‘rel’ attribute even more useful, you could structure your ‘rel’ attributes like URIs:

1

<link href="/" rel="/rels/index" />

You could then use ‘rel’ attribute URIs to provide documentation for the appropriate resource, e.g. docs for root resource would live under ‘/rels/index’. Finally, ‘/rels’ could be used to list all available documentation. This should enable users to find documentation for your API by interacting with it.