Semergence

Enjoying Sam Ruby’s latest post titled Connecting, I was reminded that designing a RESTful system means much more than just adhering to a uniform interface (often the first attribute of a ROA that is promoted).

When designing a Resource Oriented Architecture, you mustn’t forget about hypermedia and how your resources link to one another, and how those links are expressed through your representations.

Which brings me to JSON. A nifty little format, indeed. And one that, if you are building a modern web service, you should be investigating and implementing. However, if you are indeed building a hypermedia system with JSON, how do you express your links?

I know how to do this in XHTML and RDF, but not sure how to express or render a URI and have it mean “link”.

I’ve love to be able to do something like this:

{
  "name": "Cool Beans",
  "account": "http://example.org/accounts/23242342"
}

However, any JSON client will have a tough time determining what the meaning of the account value is. Sure, it’s a string. But how should it be treated? And how do I express that to my JSON clients? I’m not about to give them a regular expression and say “if it matches, it’s a URI, and follow it!”

Thoughts? How to express hypermedia in JSON?

Thinking about REST or need to address some lingering concerns about adopting REST? I found the article Addressing Doubts about REST full of pragmatic, down to earth answers and advice for comparing REST and WS-* (or, RPC).

Nothing new, but a solid collection of answers to how you should think about REST and how you should apply it to your system.

I especially appreciated how the author points out that if you are worried about transactions across your systems, that’s probably a design smell and you want to re-think your approach. Never expect that transactions will work reliably across many systems. Instead, build in logic to recover from error states. This is not a REST issue, but instead a large system design issue. REST simply makes it easy to pass the state of your resources between systems.

One of the reasons I love Rails is the built in support for REST. If you’re not yet writing your Rails applications RESTfully, then you’re not really writing web applications.

I’ll detail an example that I just created which I thought illustrated REST support quite nicely. In Rails, you can model singular or plural Resources. A plural Resource might be Users, which means you’ll have lots of Users in your system. In contrast, you can create singular Resources when there is only one instance of that Resource in the system.

A good example of a singular resource is an User’s avatar icon. For instance, most Web 2.0 applications let you upload a tiny picture that represents you. In Rails speak, we say a User has one Avatar Icon. An Avatar Icon belongs to a User.

When creating the URI space for these models (User, AvatarIcon) you use map.resources and map.resource inside of your routes.rb file. We want to enforce that an AvatarIcon belongs to an User in the URI space, and thus the modeling of the Resource. We can do that with the below routes:

  map.resources :users do |user|
    user.resource :avatar_icon
  end

Our URIs will look like this now:

• /users - list all users
• /users/1 - show a single user
• /users/1/avatar_icon - a user’s avatar icon

You can see the difference between singular and plural even in the URIs. /users is plural to indicate that it identifies the collection of all users in the system. On the other hand, /users/1/avatar_icon is singular indicating that it identifies the single avatar icon for a single user.

Furthermore, when you use map.resources, Rails will create named routes for you. This makes referring to the URIs for the Resources much easier, as they are given logical, proper names. Now, here’s where I think it gets really cool. Refer to the routes example above, where we nested the avatar_icon resource inside the users resource. When we want to create the URI /users/1/avatar_icon, we can use the generated named route avatar_icon_path(@user).

Notice how we only need to specify the user in question when building the URI to a user’s avatar icon. There’s no ID for the avatar icon in the URI, so why specify that in the named route? When I saw that, I said, “Yes, that’s exactly how I would expect it to work.”

Way to go, Rails! Making RESTful development a first class citizen for web applications.

Nearly every web application has the concept of users or accounts. While the concept of a user or account is quite universal, when you get to implementing, you find out that the business rules and implementation details vary widely from application to application. Luckily for your Ruby on Rails applications, there’s an excellent starting point for creating the basics of accounts and logins. The restful_authentication plugin for Rails provides generators for Users and the basic framework required, such as email activations, logins, passwords, controllers, and database migrations. The extra bonus is that the plugin uses REST to model the authentication.

In the REST web application world, all you see are objects, or nouns. The verbs in the system are limited to the HTTP methods such as GET, PUT, POST, and DELETE. REST advocates that you interact with the world (your nouns) with these four methods. It forces you to think, “How would I convert an Action into a Thing?”

With restful_authentication, the action is Login, but that concept is encapsulated into a Session object. When you login, you are *creating* a new Session. When you logout, you are *deleting* that Session. (Here, the Session is a different concept from a web session.) The plugin nicely models login and logout actions into CREATE Session and DELETE Session.

We can apply this concept to account activation, which I had to do recently for one of our applications. Our business rules stated that an account can’t access the system until it was activated by an administrator.

In the old pre-REST days, we might have modeled this with an action called activate, which might have set an activated bit on the account instance. Fair enough, and it would have worked fine. But this isn’t RESTful at all, as it would require a new verb in the system (activate).

Knowing that REST is all about the nouns, we noun-ify the concept of activation into a class called Activation. We say that an Account has one Activation, and if that activation relationship exists, the account is activated. If there is no activation instance for an account, then the account is deactivated. An administrator will CREATE an activation instance in order to activate an account. The administrator can later on DELETE the activation instance if they want to deactivate the account.

Another benefit of creating a first class Activation model is we can add properties such as when the account was activated and who activated it.

In summary, I love working with REST because it forces me to think in nouns, which are classes. I find it easier to model the world with nouns than with verbs. Plus, the problem with verbs is you can’t say anything about them, so you lose the ability to add metadata to the events in the system.

RESTify DayTrader, in which Joe Gregorio converts a real world J2EE application’s interface into a REST interface.

Perfect example of how to do REST with real life requirements.

A brief history of Consensus, 2PC and Transaction Commit, in which Mark Mc Keown attempts to keep us all in sync with the history of consensus across processes in a distributed system.

Excellent read. Thanks Mark!

InfoQ has an Interview and Book Excerpt from the book RESTful Web Services, the new book published by O’Reilly. I’ve ordered my copy from Amazon already, and I’m looking forward to reading it.

The interview also links to a sample chapter from the book, titled The Resource Oriented Architecture.

A great quote from the interview, by Sam Ruby:

I also wanted a book that rose above the “we are 733T, WS are the Sux0rs” zealotry that, sadly, one too often hears.

Congrats to Leonard and Sam on their book!

wadl is the Web Application Description Language, which is an XML specification to describe RESTful web services. Seeing as the current version of the spec is a mere 31 pages, I am excited to see this move forward. Many people would consider the lack of a description specification from REST web services a set back, so having a simple spec like WADL can be used to help the converts. I can see a future version of Rails generating WADL documents natively.

Tim Bray writes a nice explanation of REST. I love collecting this stuff in order to convert ^H^H^H teach my friends all about the “yummy goodness” that is REST. And hey, any name that reminds me of naps has got to be good.

Luke Redpath makes a valiant attempt to DRY up RESTful Rails controllers as he writes Refactoring REST: searching for an abstraction. I can see how this can be very useful if your controller methods follow the simple paths. Good to see some implementation patterns emerge that build on the assumptions that your controller is RESTful.