RESTful Web Services & Nirvana

I’ve been hearing, reading, and talking a lot REST, RESTful Web Services, how to implement them, and even how to explain to your wife about it. Then I see or read presentations about what is and what is not RESTful Web Services. I’ve created and consumed quite a few web services, so while I’m not a leading expert in the field, I have a lot of experience with them. So instead of explaining over and over again to different people my thoughts on the subject, I’m writing about them. For those who have a short attention span, I’ll sum up my feelings of the subject in one sentence for you, and then explain in detail for those interested.

Representational State Transfer (REST) [is an] architectural style, for distributed hypermedia systems, [that describes] the software engineering principles guiding REST and the interaction constraints chosen to retain those principles.

Period.

My feelings about REST come, almost word for word, from the opening paragraph of Roy Fielding’s dissertation on REST. REST ultimately is a set of principles with some outlined constraints to adhere to those principles. The key point is that it is principle driven. Its not a protocol. Its not a pattern. Its not a specification. REST is about fundamental principles. So that is why web services that implement REST are RESTful Web Services, not REST Web Services; and why they don’t call SOAP Web Services SOAPful.

Nirvana, The Concept

Now I’m not talking about something that smells like team spirit, but the concept and philosophy of Nirvana. I think it is good example, since it is described as being in a “perfect peace of the state of mind that is free from craving, anger, and other afflicting states.” It is this goal that millions of people living on this earth strive for, and spend life times trying to completely achieve.*

As Web Developers, we can decide if the benefits of using REST (which many people don’t even bring up when debating about REST) are worth the cost of following it’s constraints and principles. There might be projects where SOAP, XML-RPC, or other technologies are more appropriate for the situation that RESTful Web Service Deisgn (which is blasphemy to many). Once I needed to create a client and web services for a customer that might get used 3-4 times a month by a single user. On top of that, that web service would maybe serve up 300 API calls per month, if that. I didn’t need the Caching, Statelessness, and Scalability that REST can provide, so I used SOAP. One hour later, it was working great, and has been for the last five years. I didn’t have to use SOAP, I could have used simple HTTP POST’s with command names to get the job done.

The bottom line is REST is based off principles. Part of following principles is it is up to the developer on how to follow those principles, unlike a standard which instructs the developer how to follow it.

HTTP Methods

The notion of using GET, PUT, POST, and DELETE were not explicitly outlined in Roy’s dissertation about REST. It did mention GET as an example once, but the guidelines for using each of those HTTP methods was put together by other developers trying to make their Web Services more RESTful. The logic is sound, putting more information in the HTTP headers so you can cache earlier on the Application layer (example, have your web server pull directly from a cache instead of loading PHP to pull from a cache), but if a Web Service only implements GET and POST, that just means they are choosing not to try and take advantage of Caching and Layering for PUTs and DELETEs. It does not mean their web services are not RESTful. They might be a little less RESTful, but using those four HTTP Methods as a hard requirement is a misnomer.

The worst thing that has come out is many people when teaching about RESTful web services use an example performing CRUD operations. While in-an-of-itself not terrible, this leaves students without good examples of how to perform non-CRUD operations. Coupled with the extreme zeal about GET, POST, PUT, DELETE, they try to orient their entire web service towards CRUD operations, and ultimately they don’t work well. RESTful does not equal CRUD.

URIs & Implementation

I think when I read a discussion about RESTful web services, most of the discussion is about the URIs, which is ironic since it is the only one of the six constraints of REST. I think the reason is because most of these people are complaining about trying to implement others’ web services. They have the thought “Oh, if they only named the URIs in this fashion it would make more sense.” However, the style and look of these URIs are not the issue, its the uniformity of them that is important. Just like coding standards, you try to follow them as best as you can, but sometimes your names or conventions aren’t perfect. They say hind sight is 20-20, and designing web services is no different. You will make mistakes, and things won’t be perfect. The difference is you can easily refactor your code. Refactoring production URIs is much more complicated, and can break other developer’s code relying on your web services. Trust me, if there is a lesser of two evils, its not having a perfect naming convention. Pretty URLs are nice, but not an absolute.

Bending the Rule, Keeping the Spirit

I had an English professor tell me that the basic rules given to students for writing essays were to help them understand the spirit of the rules. You have an introduction paragraph, outlining your points, followed by a paragraph for each point, and concluded with a summary and statement of your purpose. She said once you understood the spirit of the rules, like keeping your paper focused, well organized, and easy to follow, then you could actual bend or break the rules because you would still follow the spirit.**

The same, I believe, goes for RESTful Web Services. Twitter seems to be the example everyone likes to use to point out what “fake RESTful” looks like. Yet, for the most part, these web services are very successful even though they are not perfect. So if my naming convention isn’t perfect, but my documentation is excellent, clear, and easy to navigate, then its alright. You keep the spirit of principle while you may not be keeping the “letter of the law” written by others about REST.

Ultimately…

Ultimately, people are still going to argue about REST. Some will treat it like a specification, a protocol almost. They will talk about how everyone else is not using RESTful web services, yet not show in production how to really implement them. Some, like the author of the presentation I linked to above, will show better ways to be more RESTful with your web services, and really help everyone learn.

Myself? I will think of REST and RESTful like Nirvana: a goal to reach and design for. Will my web services conform to the strictest interpretations and thoughts on RESTful design? Probably not. Will I lose sleep over that fact? Not a chance. Do I look forward to trying to make great web services using the principles outlined in REST? Absolutely.

Disclaimers

* – I hope I don’t offend anyone if I incorrectly portray Nirvana and it’s importance to the Buddha faith. I picked it as an example as from my own personal understanding of it.

** – This article shouldn’t be viewed as an example of my English professor’s teaching skills, since I didn’t spend nearly as much time writing it out as I do for full articles. She was an excellent teacher, and taught me how to write very well (at least I think so, I hope).