But you probably haven’t heard of ASCIIcasts, which is a text version of the original blog, including a transcript of Ryan’s voice from the original video, along with key code samples and screenshots of the main features explained. Think of it as a textual equivalent of the screencast. It can serve various purposes, including being search friendly (you can make a full text search on Ryan’s spoken words), but also for people like me with a slow connection, it can help me have a glimpse of any episode before actually downloading it, maybe even sparing me the effort and bandwidth. If any of these or other reasons are good for you, or even for the sake of it, take a look as ASCIIcasts. You’ll love it almost as much as the original.

It allows you to select what version of Rails (and Ruby) to browse, and the most awesome part is that you can download a compressed package to browse it offline locally in your own computer. It includes Rails 3 beta and Ruby 1.9.x as well.

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.

So far (the short version) I am doing better than I thought for just about a couple of days being serious about this. There are a few things that still bother me a lot though, aside from the fact that I am not proficient using it yet, of course.

My [mostly borrowed] customizations

I’ve heavily customized Emacs to suit my needs better than it could do with its awkward defaults. Emacs key shortcuts (or is it key bindings?) are soooo unpleasant, unintuitive, lengthy and annoying that I refuse to use them at all. Happily one of Emacs’ most powerful strengths, its ability to be customized, comes to the rescue. Actually this feature is what makes Emacs still relevant after 30+ years.

My Emacs after being customized

Without going too much into details, I based my Emacs customizations mostly on Ryan McGeary’s, mostly because his setup is aimed at Ruby on Rails development and Git, which is what I want Emacs for in the first place. Overall, it’s ri-emacs, rinari, rhtml-mode, magit, yasnippets, and several other non-language-specific customizations (ido, recentf, etc.)

On top of this setup, and after pruning stuff that I don’t need, at least for the moment (like erlang, markdown, haml, svn, carbon-emacs, etc.) I added support for some other stuff, namely rspec, cua-mode (see Common User Access), and other minor goodies from other sources.

Aside from McGeary’s setup as a base, I have to give credit to snippets of code I borrowed from elsewhere to further customize my environment. I should particularly mention Devcraft’s advises to customize Emacs for Rails development, Dahoiv’s .emacs file, the Emacs blog (where Ryan McGeary also writes) and the emacs-flu blog.

Pros and Cons

On the good side, I have played for a while with the ruby on rails mode and it is good. The yasnippet extensions take a lot of credit on this, but overall it tastes very good on its own. I have yet to deal enough with the magit extension to fully evaluate my environment. I cannot afford buying a Mac+TextMate for Ruby development, and Emacs can hopefully come to the rescue for my productivity and joy while coding.

Also, having been able to get rid of most of the many painful key bindings in such a short time was amazing. I wonder why Emacs does not update its defaults to comply with the CUA standards. The cua-mode is not enough.

On the bad side (taking aside my own inexperience and lack of abilities) not everything is doing fine. Many of my key-bindings customizations break on “weird” modes, like C-w for closing the current buffer, which is not working when the current buffer is in dired mode.

Also, I feel disappointed with the embedded shell (M-x eshell). I actually expected a bash session inside an Emacs window, but aliases and tab-completion are not working as they should, which makes me suspect it is not bash but an Emacs shell program (surprise!!!). As it is right now, I prefer to Alt-Tab to my terminal emulator with a real bash session in it. Something similar happens with the Rails console (available via C-c ; c), which I really didn’t test a lot after I realized that pressing the up and down arrow keys didn’t navigate through my history of previous commands .

So, what is it then?

In spite of all this, I still believe I can give Emacs a chance. Most shortcomings I’ve faced are not directly related to its function as a coding environment, but to tasks around coding, like going to the console to type rails-related commands, manipulating the file system, etc. I was doing these stuff outside my previous code editors anyway so I guess this can stay as is for some time.

Hopefully I’ll be able to fix some of this issues over time and always use more and more features of this wonderful editor. I could even live without using git from within it, but I have yet to test that. Meanwhile, I’ll take some time to get better at coding with what is currently working for me. It seems to me that Emacs will stay for a while on my desktop.