REST Issues, Real and Imagined

Tuesday, 27 February 2007

I think that most of the debate about REST focuses on the wrong things, leading developers down the garden path at the expense of their productivity and the success of their projects. Time and time again, I’ve seen folks who are new to REST get caught up on small stuff like this;

False Choice: “High” vs. “Low” REST
Lots of blog space has been devoted to figuring out what PUT and DELETE are good for, leading many to believe that they have to choose a direction, “High” or “Low” (as popularised by Don). I’ve seen developers who decide they can’t do “pure” REST, and so think that the only alternative is POX-style RPC services, with nothing in between.

This isn’t an earth-shatterning choice to make; the truth is that you’re just choosing what methods you’ll use, based on the semantics of your application, and how well those methods are chosen by the tools you’ll use. Is this a reason for a schism in the Web? Hardly; there are much more fundamental splits in WS-* services (e.g., whether to use SOAP encoding, RPC, etc.).

Red Herring: The Evils of POST
If you dip into REST discussions a bit, you may leave with the impression that POST is the anti-REST, and it should be avoided at all costs. However, if that’s true, why did the Great Roy allow POST to be foisted upon HTTP? Perhaps it has a place in RESTful applications after all — as long as it’s used intelligently.

This usually becomes obvious when you’re deep in the bowels of resource-modelling an application, trying to figure out how to represent a complex operation as state — only to realise that there’s no need to expose all of the details, if there were just some way to say “hey, submit this for processing!” POST is the correct answer.

Red Herring: URI Design
When somebody first “gets” REST, they often spend an inordinate amount of time agonising over the exact design of the URIs in their application; take a look over on rest-discuss, for example. In the end, though, URI design is a mostly a cosmetic issue; sure, it’s evidence that you’ve thought about good resource modelling, and it makes things more human-intelligable, but it’s seldom worth spending so much time on it.

I’d worry a lot more about cacheability, extensibility and well-defined formats before blowing out my schedule on well-designed URIs. For me, the high points are broadly exploiting the hierarchy, allowing relative references, and making sure that tools (e.g., HTML forms) can work well with my URIs; everything else is gravy.

Red Herring: Cookies Are Bad
Cookies get a lot of grief, and they are certainly abused on the Web today. However, they’re not intrinsically bad; there are uses where they’re appropriate, as long as they don’t try to do the job of the URI as well. Given the poor state of the standard mechanisms for HTTP authentication, for example, it’s not unreasonable to use them for passing credentials.

False Choice: Machines vs. People
There’s an insistence from some quarters that somehow, HTTP and REST are only good for people sitting behind browsers. I think that this has been solidly and obviously disproven, and find it difficult to believe that such continued, vigourous assertions are anything other than FUD. shrug

How About Some Real Issues with REST?

All of the above is not to say that there isn’t anything to improve about the state of HTTP and REST in the world.

The most obvious issue that everybody trips up over is authentication — HTTP authentication is unbelievably primitive, and while there are promising things on the horizon, we’ve still got a long way to go.

Another issue is shared with ws-* services; formats are hard. In particular, while XML is popular, most use of it is horrible, and the tools don’t encourage good practice. You could count the number of people who can write an XML schema that’s extensible and versionable on both hands. JSON is promising, but it doesn’t have a schema language, and it’s also pretty limited.

The tools for REST are primitive as well; Marc’s JSR looks promising in this direction, but a lot more work needs to be done, in a number of dimensions.

Finally, one of the deeper REST constraints is using hypertext as the engine of application state. Designing applications and tools that are smart enough to update themselves based upon what happens on the Web isn’t in reach for today’s tools. That’s not to say that they’re not possible.

14 Comments

Mike Schinkel said:

Really nice post. I strongly agree that REST is a great (dare I say ‘better’?) solution and I appreciate your championing the cause. And I think your points are spot on. Except one. URI Design does matter. You can read my full comments on the matter at:

http://blog.welldesignedurls.org/2007/02/28/sorry-mark-url-design-does-matter/

Wednesday, February 28 2007 at 11:06 AM

Mike Schinkel said:

Mark: Thanks for responding. In my post I meant to address was human vs. machine consumption by as I fell asleep writing it and published the next morning, I forgot to mention it (Doh!)

What I would have said is that, yes today there is a clear delineation between HTTP services used by man vs. by machine. However with the advances in and usage of semantic markup, some of which I hope to help drive with Toolicious [http://t.oolicio.us], I think that we’ll see a blurring of the two to the point where most URLs published will be designed for consumption by both. And if I am correct and we do see this convergence, published guidance on REST stating that URL design is unimportant will set a-less-than-ideal precedent. And by making an issue of it this is what I’m hoping to avoid.

On the other hand if this convergence I predict does occur companies won’t necessarily need to build two sets of services, one for man and the other for machine, except for specialized processing. And it will fuel appreciation of RESTful architectures and best practices, even for human-focused sites, in part because it will allow site publishers to “kill two birds with one stone.” And I think this is something that both of us can agree on would be a good thing, no?

Thursday, March 1 2007 at 1:54 AM

Mike Schinkel said:

P.S. You can send those guys calling late at night wanting their URL designed reviewed to me. I’d be more than happy to help them! (And late at night your time is my day time, I believe. ;-)

Thursday, March 1 2007 at 1:57 AM

pwb said:

Thanks for the post but this still doesn’t help. Until there is some consensus around how a RESTful API would actually look, REST is hopeless for APIs. We need more than a dissertation or an “architectural style”. For better or worse, at least SOAP tells you what to do!

Thursday, March 1 2007 at 2:12 AM

Mark Nottingham said:

Mike,

The scope of my post is largely REST for machine consumption (i.e., “services”), and most of my recent experience is for REST services inside the firewall. For human-consumed resources, as well as for services outside the firewall, I agree with you.

The problem that I was trying to address was indeed developers who over-focus on URI design; I’ve had anguished late-night calls from folks who want to know if they’re designing their URIs correctly, and I don’t have the heart to tell them that there isn’t any real difference between the two approaches they’re considering, because they’re equally RESTful.

Cheers,

Thursday, March 1 2007 at 2:21 AM

Yaron Y. Goland said:

At the risk of being flamed out of existence I just wish there was a definition of REST that didn’t run to hundreds of pages. If you can’t hit the highlights in a page then it’s too complicated to be terribly useful. Of course everytime I see highlight articles the highlights appear to be different. So, for me, I still don’t know what REST means in any useful sense. But I long ago accepted that I’m slow.

Thursday, March 1 2007 at 3:56 AM

Sylvain Hellegouarch said:

I think you should be careful to disregard URI design like that in a blog post. Some people may read it as “Mark said it was worthless so I don’t have to think about it” (some people are funny like that).

I think the URI design is important if you consider your URI as your public API of your web service.

If the API is poorly thought then the service will be poorly implemented and used. URI design may not be the core part of REST but is certainly an important one on the long run. What I think you’re trying to say is that URI should be loosely coupled with the backend system handling them so that they can be changed while keeping the system coherent.

Thursday, March 1 2007 at 6:27 AM

Paul Downey said:

What Sylvain said - whilst URIs are opaque and don’t need to be human friendly for caching, it sure helps when it comes to templating - I guess I need to see your programming model for “Hypertext as the Engine of Application State” as that’s something many people, including myself, struggle with - both understanding and saying. It’s pretty opaque ;-)

Thursday, March 1 2007 at 10:09 AM

Pete Lacey said:

Yaron,

“…I just wish there was a definition of REST that didn’t run to hundreds of pages.”

http://www.megginson.com/blogs/quoderat/2007/02/15/rest-the-quick-pitch/

Friday, March 2 2007 at 12:41 PM

Mark Nottingham said:

I’m going to continue pushing back ever-so-gently on the URI design proponents.

Yes, it matters, and people should think about it. I’m not saying it should be ignored or minimised.

The problem that I see is that people seem to think that there’s some magically perfect URI for their application, and they set off on a quest to find it, to the exclusion of all other considerations.

In almost all cases, there are a multitude of good RESTful URIs for a concept, not just one. Many of the considerations are practical (e.g., will it work with relative URIs? Will it be cacheable? Is it extensible?), not theoretical, but people seem very inclined to focus on the theory, IME.

Saturday, March 3 2007 at 5:24 AM

Jim said:

Good post. I should point out that OpenID doesn’t really fix issues with HTTP authentication per se. OpenID is instead a solution for simplifying identity management across disparate services.

Saturday, March 3 2007 at 5:42 AM

Ryan J. McDonough said:

Your points on “High” vs. “Low” REST are spot on. The fact is there are light weight clients out there (Flash) that don’t support PUT & DELETE and you don’t really have much choice other than to use a POST operation. POST can still be RESTful if its applied properly.

Sunday, March 4 2007 at 12:14 PM

Stefan Tilkov said:

I think people focus on URI design since the usefulness of URIs is the benefit of REST that’s the easiest one to understand. Considering URI design as the quintessential REST design activity is very tempting …

Tuesday, March 20 2007 at 6:24 AM

pacoit said:

It is unnecessary and bad functional design to use or rely on URIs as an API with REST. It’s unnecessary because navigating hyperlinks is the intended method of resource discovery. Ideally you can use topic maps, faceted classification, or other techniques to filter your way to the desired resource. This works for humans, who then bookmark the resource for the next time. A link can be included for an XML, JSON, YAML or other representation, which should also include navigational links, for machine use. But it is easier for a user to find a resource once and bookmark it than it is for a programmer to figure out a script to navigate machine responses to reach the same resource. URL APIs are bad functional design because you don’t really want users to navigate a site by guessing at URIs. REST is easy. It’s like navigating a 1st generation website: every resource has a URI.

Saturday, May 26 2007 at 11:36 AM

mark nottingham

what others are reading