The Human is a RESTful Client

There’s plenty of great technical writeups and non-technical writeups on REST. In short, REST is one way to model and present your data to your users in a consistent, logical fashion that lends itself to being accessible humans, machines, and your own developers. (I don’t know if I just called developers neither human nor machine, but let’s go with it.)

There’s a number of great technical reasons to move to an architecture like REST. In fact, there’s a number of great reasons to implement SOAP, XML-RPC, or similar architecture on your app, the distinctions being less relevant for this post. But REST isn’t just for API clients or web browsers: REST is for people, too.

Part of what REST does really well is help you to define the resources for your app. User, Post, Tag, Comment… all of these form the concept of a blog. By defining your structure this way, not only can you craft a machine-readable and machine-writeable interface for your site, but you can end up centering your UI around this, too. It’s easy enough to scaffold your usual CRUD of an app: a barebones form to create a new Post, a page to show that Post, an index page to list Posts.

Humans understand this. I’d wager even your stereotypical I-don’t-understand-computers Farmville player has a basic grasp on the basics of REST, even though they haven’t the foggiest of what a “resource” is. They might not know how to do something upon first visit, but they know what resource they want to interact with. Posting a comment on a blog post? Look for the form labeled “New comment”. Signing up for an account? Look for the “New account” button. As long as the resources are basic and intuitive — “create a new TransientSubscriberSubscriptionNode” might be slightly too complex, for example — humans are going to have a good chance at figuring out how to work with your objects.

This is all pretty straightforward, of course. A comment on a blog is simple enough that it’s hard for anyone to get that wrong. The problem is when you bleed between objects or devise complex on-page ajax interactions. I have nothing but reckless intuition to back this up, but I’d bet that the majority of the most-confusing forms and interactions online stem from a failure to separate resources sufficiently, or a failure to properly define resources for your app (one resource doing the job instead of splitting things up into smaller pieces, for example).

Admin screens are a magnet for this. The noble idea is to have a few screens to manage as much data as possible, since we really care about efficiency and flexibility and productivity and other words ending in -y. This is where the minefield of checkboxes and radio buttons and dropdown filters come from when you’re trying to graft one screen onto multiple interactions with resources that are sort of related but not exactly related. Yes, it can certainly work, but the more you drift from that simplistic, single-resource mindset, the harder it is to intuitively grasp what the hell’s going on here. And sure, you can add help text and documentation and mouseovers and plenty more to explain how all these doohickeys interact with the data, but that just means you have a more complex screen that’s harder to use and harder to get others to use. This doesn’t even take into account the harder technical hurdles you face with complex screens, either.

It’s not just admin screens, of course. Complex, multi-page signup forms may expand beyond just the User object and into other areas (Profile, Social Networks, Preferences, Billing, and so on). There may be a tendency to have a listing page that offers inline editing, state changes, and child creation for each object on the page. The listing page may, in fact, list a mixture of four separate resources rather than having four discrete lists. By bypassing the simple and straightforward, the user has to sit and think about how they might go ahead and accomplish their goal. I don’t know about you, but users aren’t the brightest tool in the shed, so leaving them to their own devices to think for themselves probably will sink your company and likely will cause California to sink into the ocean.

I’m not saying any of these are wrong, of course. REST is meant to be broken, really. It’s not entirely all-encompassing; we’ve all skimped on a show action when the data is small enough to put on the index action, or we’ve added a few actions to help separate out complex state changes. But every time you cram more interactions into your controller than those magic seven actions or try to consolidate multiple resources into one page, you’re not just going against the REST implementation grain; you’re going against what might be the most intuitive route for the user.