Rails has to be credited for introducing RESTful design to so many people, including me. I bet most web developers out there first knew about it from Rails, particularly from its 2.x release series, that have adopted resource-oriented design more seriously. The main benefit of adopting a REST-like architecture is that there’s a relatively easy and straightforward way of adding an API to our applications without developing an extra backend.

But Rails didn’t get it completely right, perhaps intentionally, with the outcome that there are so many people out there thinking they are developing RESTful applications.

To understand why, let’s review the original concept of REST, something I never did when I took it for granted from the Rails implementation.

Defining REST

REST stands for Representational State Transfer, and it is an architectural style for distributed hypermedia systems. This is the concise and original definition of its intention, according to its creator Roy Fielding in the paper that started it all.

But perhaps more digestible and to the point than this paper is a blog post recently published by Paul Sandauskas in his blog, where he warns developer about not being fully compliant with REST guidelines. The short story is that resources should be hyperlinked to express their relationships, and client applications of a really RESTful API should be able to “navigate” across the exposed resources without previous knowledge of the URI structure, beyond an initial entry point, which could be the analogy of a home page for a regular web site.

I really recommend you reading Paul’s article, since I won’t go into the many interesting details. Overall, the advantages are many: clients need to have no knowledge about the structure of the resources in the server’s URI space beyond the starting point, so the application provider can make structural changes without “breaking” the clients.

There’s plenty of information about REST out there, independent from the Rails point of view. For a start I recommend the REST wiki, Wikipedia’s article about it, Roy Fielding’s dissertation (in particular chapters 5 and 6) and google of course.

RESTing on Rails

Rails tries to comply with REST and it’s great at it. But not fully compliant. Not that this is a bad thing though, and it’s even perhaps intentional (I don’t know). At least the most important REST guidelines are supported, particularly the URI-to-Resource mapping, avoiding a RPC kind of design.

So where does Rails fails? Mainly at not expressing relationships between resources by including hyperlinks in a resource’s representation (after all, that’s what hypermedia means). This, seen from an API point of view, where representations are often XML or JSON for the consumption of a client application, hinders the ability of the system to survive structural changes in its design and its URI space without rendering all independent clients useless.

For example, imagine a client application connecting to the API exposed by your own application, and requesting information about the products you offer. A reasonable response by a rails application conveys information about the product name, description, price, and the internal auto-generated id.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<products type="array">
  <product>
    <category-id type="integer">3</category-id>
    <description>Just a couch, as you would expect.</description>
    <id type="integer">1</id>
    <name>Couch</name>
    <price type="float">123.45</price>
  </product>
  <product>
    <category-id type="integer">6</category-id>
    <description>For your kid to pretend he's a hero.</description>
    <id type="integer">2</id>
    <name>Spiderman T-Shirt</name>
    <price type="float">12.95</price>
  </product>
</products>

The client application retrieves this XML representation of the resource but to request a single product resource from this list, it needs the URI identifying such resource. But what URI identifies each independent product resource? The client needs to know how the URI structure of our site works, and needs to construct URI’s based on this and the id of the desired product.

But what if we decide to restructure our web site in the future, and resources are no longer referenced the same way? All independent client applications are suddenly broken, or else we are stuck with our initial design choices so we don’t piss off our clients (who wants that after all?).

Why don’t we “navigate” through the resources exposed by our API instead? This implies conveying also hyper-textual information. After all, that’s what we do when we as human users enter an e-commerce web site (or any other web site). The HTML web pages are the resources we consume, and the browser is the library we use to connect to the internet. We don’t know in advance, from a page with a list of products, what the URI’s are for each independent product. That information comes with the page. If the developers decide to change the URI structure of the web site in the future, we can still navigate across the site when we visit it again, provided the initial entry page (the home page) is the same.

So REST is nothing more than just applying foundational web principles to modern web-based programming interfaces.

Does it really matter? Why bother?

It doesn’t really matter, if you are just using your Rails application in a closed environment, that is, if not even you consume the API but just the regular HTML interface, or if you are the only consumer of the API of your own application.

But what if your application is cool and useful enough so that third party vendors start using it to integrate their systems with yours? Isn’t that good? And what if you decide to re-engineer your site in the future and all those non-human API-consumer clients start broking? You’ll either have to…

• …continue supporting the old and the new interfaces at the same time (more work for you),
• …or convince your clients to re-program their interfaces with your application (more work for them),
• …or just let them go for a better provider (you loose).

Of course, you can always drop those pesky plans of re-engineering, but then you are stuck with your initial design choices, as far as they concern the external interface. Why condemn yourself with something that seems good today but might be holding you back in the future?

For Rails applications developers like me, there’s not much of a choice, but I wonder why Rails decided to auto-denominate themselves RESTful when they aren’t really, in the most strict sense of the word.

Pedantry? Perhaps.