cfis : Why Is REST So Hard to Understand?

Comment on Why Is REST So Hard to Understand? by Peter Williams

Mon, 13 Aug 2007 10:12:27 -0600

The term “ROA” is a bit of a problem in the context you are trying to use it. Namely, it seems to be already used in the REST community to describe applications that are “resource” oriented but have missed the fact that the most single most important thing about REST is the hypertext.

Comment on Why Is REST So Hard to Understand? by Charlie

Mon, 13 Aug 2007 10:30:06 -0600

Hey Peter,

Its hard to say that hypertext is the most important part of REST since without resources and URI’s you couldn’t have hypertext.

I think my use of ROA is appropriate - the focus of the architecture is on the resources and not the services.

Comment on Why Is REST So Hard to Understand? by Sean Gillies

Mon, 13 Aug 2007 10:34:38 -0600

Like S3?

Comment on Why Is REST So Hard to Understand? by Jeremy McAnally

Mon, 13 Aug 2007 10:35:04 -0600

I think it’s hard to understand because people use hard words to describe it. A lot of the terminology I see in “introductory” articles would (and should) put the REST newbie off.

Comment on Why Is REST So Hard to Understand? by Peter Williams

Mon, 13 Aug 2007 11:11:04 -0600

I say that hypertext is the most important thing because if you have “hypertext” you MUST have global name (URIs) and resources. You can conceive of global names without hypertext but an architecture comprised of just resources with global names does not hold nearly the same potential as a fully REST based system with hypertext.

Comment on Why Is REST So Hard to Understand? by Charlie

Mon, 13 Aug 2007 11:11:04 -0600

Hey Sean,

What do you mean, like S3? Are you using it as an example?

Comment on Why Is REST So Hard to Understand? by Charlie

Mon, 13 Aug 2007 11:13:49 -0600

Jeremy,

I agree - people tend to dive right into resources, uris, http verbs, idempotent, GET vs PUT, etc. Unfortunately, the recent article on Directions magazine (link is in first paragraph above) is a good example of causing more confusion than enlightenment.

Comment on Why Is REST So Hard to Understand? by Charlie

Mon, 13 Aug 2007 11:23:31 -0600

Peter,

I’d agree with the statement that hypertext brings together all the pieces of REST (resources, single API, URIs, hyperlinked representations) and shows its full power. So I think we are in agreements - REST without hypertext would negate many of the benefits.

Comment on Why Is REST So Hard to Understand? by dstar

Mon, 13 Aug 2007 12:19:39 -0600

A large part of the problem is that I have yet to see an article that explains

a) Why I, as someone with an existing rails app, would want to refactor it to be RESTful b) How to do so via simple examples

but doesn’t

c) Assume I already know the terminology

A related issue is that all the articles I’v seen so far seem to think that because I’m building a RESTful app, I want to be serving XML and HTML and perhaps other formats via the same action, which is orthagonal to REST and does nothing more than complicate the issue (indeed, one article I looked at seemed to thing that moving to REST was the only way to do so).

I’d really like an article that fit criteria a, b, and c – I don’t suppose you know of one?

Comment on Why Is REST So Hard to Understand? by Sean Gillies

Mon, 13 Aug 2007 12:23:51 -0600

Yes, I meant S3 as an example of a services that eschews links.

Comment on Why Is REST So Hard to Understand? by Charlie

Mon, 13 Aug 2007 12:36:12 -0600

Dstar,

I took a stab at a) and b) last year - see my article about a REST Controller for Rails.

As for c), I like Joe Gregorio’s articles on xml.com

And for your last point, it is part of REST since a resource can be represented using any number of formats (HTML, XML, JSON, ATOM, etc.). But whether you want to do such a thing or not is up to you (I find it helpful, see my article about content negotiation).

Comment on Why Is REST So Hard to Understand? by Charlie

Mon, 13 Aug 2007 12:39:15 -0600

Sean,

Ah. I wasn’t eschewing links though, did I come across that way?

Comment on Why Is REST So Hard to Understand? by dstar

Mon, 13 Aug 2007 12:45:24 -0600

Charlie,

Thanks for the pointer – that helped a fair amount. I do still have some questions, though.

For example, in my app, I have Stories, which have Chapters. I have two seperate actions which correspond to show – show, which shows the chapter in its normal form, and show_draft, which shows comments and includes links to edit the individual paragraphs. How could I map both of those to a GET operation? It seems to me that I’ll have to include the action in the URL after all, to disambiguate.

Comment on Why Is REST So Hard to Understand? by Sean Gillies

Mon, 13 Aug 2007 13:05:42 -0600

I don’t think you did, Charlie. I was just offering a concrete example to help people understand comment #1.

Comment on Why Is REST So Hard to Understand? by Charlie

Mon, 13 Aug 2007 13:37:39 -0600

Dstar,

There are two things here. First, you have “nested” resources. From the outside, the url could look like this:

/stories/1/chapter/2

As far as editing and showing a draft, what we do is:

/stories/1 /stories/editor/1

Thus a story editor is separate resource.

There is a no clear “right” way to do this, what we do is different than what the Rails core teams suggests. The link above talk a bit about this issue. Also, Peter recently wrote an article about nested resources you might want to look at.

Comment on Why Is REST So Hard to Understand? by Charlie

Mon, 13 Aug 2007 13:38:01 -0600

Sean,

Doh - now I get it! Sorry for my confusion.

Comment on Why Is REST So Hard to Understand? by dstar

Mon, 13 Aug 2007 13:57:13 -0600

Okay, I think I get it now – instead of ‘show’ and ‘show_draft’ actions, I would treat them as separate things: /stories/1/chapter/draft/1 /stories/1/chapter/1/

Comment on Why Is REST So Hard to Understand? by Charlie

Mon, 13 Aug 2007 14:14:45 -0600

dstar,

Yup, that’s what I would do.

Comment on Why Is REST So Hard to Understand? by Jeremy McAnally

Mon, 13 Aug 2007 16:56:54 -0600

dstar: It would actually be /stories/1/chapter/1/draft

Comment on Why Is REST So Hard to Understand? by Espen

Tue, 14 Aug 2007 01:51:24 -0600

Your article did at least give me a new perspective on a subject I am struggling to understand.

Comment on Why Is REST So Hard to Understand? by Dennis Doubleday

Tue, 14 Aug 2007 12:04:16 -0600

Thanks for the interesting take. I need to learn more about REST.

But I’ll provide some feedback anyway. I think REST proponents tend to hand wave away the complexity of large scale distributed systems by saying, “look, it’s just URLs and a few simple operations.”

Well, yes, but the innate complexity of the system is still there, it’s just expressed differently. Suppose you need to do 100 different things with data. You can write an API with a 100 different service methods, or you can have 4 methods and move a lot of the complexity into the data itself.

And the various manifestations of SOA spend a lot of time and complexity on describing data in generic, cross-platform ways because it is HARD to make things interoperable. I believe those difficulties still exist in making REST resources interoperable, but the culture allows for a certain amount of “we’ll make it work” rather than nailing down all the details.

Finally, “How well does the ROA approach work in the real world? Well, the web is the most success distributed computer system in the world, so I would say quite well.”

I don’t think that is proof at all. The web is VERY forgiving of errors, missing resources, and inadequately structured data because navigation of the web is primarily driven by human intelligence, which can handle sloppiness better than automated distributed systems.

Comment on Why Is REST So Hard to Understand? by Charlie

Tue, 14 Aug 2007 14:32:31 -0600

Hi Dennis,

Thanks for your thoughts.

On your first point, remember in SOA that interoperability can only happen when a client and server can find each other (via a URI on the web), agree on an API and agree on a data format.

In ROA the API barrier is removed - a client and server have to find each other and agree on a data format. So now you only have to solve the data format issue.

So I agree the data format (representation) is very important, but in practice it has turned out be solvable since ROA makes the representation a point of extensibility (for example, in the last few years we’ve seen RSS and Atom emerge as new agreed-upon representation formats).

As far as the existence of the Web not being proof that it works - I have to disagree with you there. Sure the Web is forgiving - but maybe that means you need to have a forgiving system to scale globally. Also navigation is driven by links - machines can follow them just as well - otherwise Google wouldn’t exist.

I do agree for automated systems, HTML/XHTML leave a lot be desired as formats - but that’s ok because for automated systems they’ll be replaced by Atom and the Atom Publishing Protocol as I’ve talked about before.

Comment on Why Is REST So Hard to Understand? by Jeremy Cothran

Wed, 15 Aug 2007 08:36:34 -0600

Hi Charlie,

Thanks for the articles and explanations concerning REST and ROA. Hopefully we’ll be able to go back to putting the services/software cart after the data/format horse instead of the other way around.

My focus has been on format with ObsKML http://nautilus.baruch.sc.edu/twiki_dmcc/bin/view/Main/ObsKML for my work with observations systems, in utilizing KML’s Metadata tag to help with data reuse beyond the limits of the single string description tag only.

Comment on Why Is REST So Hard to Understand? by Samuel A. Falvo II

Wed, 15 Aug 2007 09:44:15 -0600

Take a look around - when is the last time you saw a large distributed computer system working across multiple organizational boundaries that is based on COM, CORBA, RMI, SOAP web services, etc?

Every single day of my life. In fact, I help maintain software which is based on proprietary RPC calls. Previous lifetimes has seen me developing user management systems for ISPs using CORBA. And somewhere in the middle, I worked for a company that used SOAP pretty well exclusively to make its internal software work.

So, yeah, I’ve seen these packages running and the benefits to society that they offer VERY often indeed. And I continue to use and support them today.

Comment on Why Is REST So Hard to Understand? by Samuel A. Falvo II

Wed, 15 Aug 2007 10:15:27 -0600

Anything of interest gets a globally unique identifier, which is done via URIs.

CORBA objects each receive an IOR, guaranteed to be unique in the known universe.

Next, the service becomes uninteresting because every service has the exact same API. On the Web, the service API is defined by HTTP verb’s GET, POST, PUT, DELETE, etc.

This is not an API. This is a networking layer. Sure, it’s an API between web browser and web server, but this “transport” (as it’s called) is completely transparent to the higher-level software.

Likewise, CORBA also implements its own transport that is demonstrably superior to HTTP. It’s stateful, thus eliminating outright the need for the megabytes of software that exist PURELY to manage cookies, sessions, and other bizarre concepts.

Since all interesting data has a globally unique identifier, it becomes possible to create a web of links

Since all CORBA objects refer to other objects via their IORs, CORBA also supports creating a web of object links.

Since there is only one service API, it becomes possible to create a single client (think of a browser) that can access an infinite number of services (think of websites)

This is actually false on the global scale – that is, it is true ONLY for a certain subset of applications (namely, those applications whose data is formatted conveniently for human consumption). For all others, you end up base-64 encoding binary data, thus resulting in 25% additional bandwidth overheads, or worse, using XML to encapsulate data structures which are well known to both sides of the connection, thus increasing bandwidth requirements to an amazing 200% to 500% in the process.

EA-IFF-85a files are binary files with recursive descent characteristics – they solve the exact same problem as XML does, but it does so without the bloat of XML. It allows for textual or binary data (indeed, IFF files are designed specifically with binary files in mind). But, alas, it died out, having been seen ONLY as a “file format for that Amiga platform that nobody SERIOUS uses.”

I’ll admit that there is SOME coupling that occurs with CORBA’s IIOP protocol, but let’s not forget that both the client and the server have to agree on an interface to communicate to begin with. Since both interfaces are already known in advance on both sides of the connection, IN PRACTICE, tight coupling at the IIOP level has not been a problem.

Versioning of interfaces happens by changing the name of the interface. If I release an object that implements Foo, and suddenly I find I need new functionality in Foo, I might re-release the object as Foo2, which inherits Foo as a base interface to support backward compatibility. IIOP allows this, and even encourages this.

Versioning issues between clients and services are greatly reduced (although they still happen when HTTP changes)

They still happen even when HTTP doesn’t change. Remember, HTTP is used only as a transport.

See above point on how IIOP/CORBA handles versioning of interfaces.

State can be taken out of the system and made into its own resource, thereby making the system much more scaleable

IIOP connections are stateful in nature, and that is true. But that doesn’t mean the objects behind them have to be stateful. Indeed, architecturally, there is NO difference between a CORBA ORB and an HTTP server. None. The difference lies in how the connections are managed. As soon as an HTTP server is done spewing porn, spam, and advertisements down the pipe, it closes the connection. As soon as IIOP is done spewing, the connection remains live.

In order for a service built on top of HTTP to remain stateful, complex mechanisms employing cookies and “sessions” are required. An incredible amount of software goes into maintaining sessions – so much so, in fact, that most languages now have specialized web design toolkits (Ruby on Rails, Zope, etc) which abstract away much of this duldrum.

CORBA does not need this kind of complexity, since the objects on the other end CAN reliably be stateful. And, if the connection is lost for some reason, you can reconnect to that object and pick up where you left off (unless it’s a transactional object, in which case you’ll need to start your transaction over).

In retrospect, it is patently clear that there is nothing new under the sun here. Just as those who are unaware of Unix are doomed to repeat it, poorly, so to is the case with distributed services: those who don’t know CORBA are doomed to repeat CORBA … poorly.

There is a silver lining to this tornado cell though. For those who are able to stretch their imaginations a bit, and are even half-way familiar with Haskell, you can think of the session management functionalities as implementing a state monad. Therefore, the HTTP approach tends to be look “functional” in nature; it has to, as the protocol is a stateless protocol. The only way to reliably maintain state from page to page, therefore, is to pass your state around as hidden form entries or as parts of the URL (both of which are considered “parameters” to the web-based functions you’re hitting).

Unfortunately, this state monad is muddied by the fact that you’re now maintaining state in a database, which just screams for an imperative method of programming. If we’re going to be using state monads to model state in a program, then there is certainly nothing preventing the use of CORBA at the level of a functional program either, since socket I/O is just another case of using a state monad.

We’re back once more to where CORBA shines and HTTP is simply inadequate.

Comment on Why Is REST So Hard to Understand? by Charlie

Wed, 15 Aug 2007 12:23:03 -0600

Hi Jeremy,

Thanks for the note and link. Funny for me to say this - but have you looked at the observation functionality built into GML? I haven’t used it myself, so no comments on its suitability for what you need.

Comment on Why Is REST So Hard to Understand? by Jeremy Cothran

Wed, 15 Aug 2007 14:39:05 -0600

I hadn’t taken a look at GML’s observation functionality, but based on the description(fields are time,location,resultOf,using,subject) at http://geoweb.blog.com/313930/ it doesn’t provide the level of detail that I’m looking for directly although the ObsKML schema which provides the necessary detail(an observation list bound by the same time/location with each observation having a observation type, unit of measure type and measurement value(and optional elevation) could be linked/nested within GML,etc similar to what I’m doing with KML.

Comment on Why Is REST So Hard to Understand? by Oisin Hurley

Wed, 15 Aug 2007 14:46:17 -0600

Samuel said:

“This is not an API. This is a networking layer. Sure, it’s an API between web browser and web server, but this “transport” (as it’s called) is completely transparent to the higher-level software.”

One of the core issues here is whether you approach solutions as a ‘layerist’ - that is, you isolate the protocol from the programming, as CORBA does, or an ‘applicationist’ - the protocol directly maps to the agent that is to process the request.

Your statement above indicates ‘layerist’ thinking, however most REST aficionados (and certainly ones that use HTTP as the basis for examples), will be part of the ‘applicationist’ camp.

This fork in thinking is a vital and fundamental differentiator - for the REST-with-HTTP guy, those POST/PUT/GET methods are the API, the API to a resource.

Comment on Why Is REST So Hard to Understand? by Charlie

Wed, 15 Aug 2007 15:52:51 -0600

Hi Samuel,

Wow - you win the contest for submitting the longest comment in the history of this blog. Let me respond to a couple of things you said, although maybe the better idea would be to write another post.

To start, I’m not anti-CORBA or anti-JMI or anti-DCOM, etc. Such systems provide a workable solution within organizations - however I do not think they work inter-organizationally. I would be interested in hearing more about the examples you mentioned in your first comment.

Next, I’ll disagree with you on HTTP - its a transfer, or application, level protocol and thus its purpose in life is to provide a single API for clients and servers that support it. No doubt HTTP has been abused by various protocols that simply use it as a bit stream to avoid firewalls, but that’s not HTTP’s fault.

Now is IIOP better than HTTP? Is a non-question since they are such different beasts. HTTP is stateless, text-based protocol designed to provide a single application level API used to tranfer chunks of content. IIOP is stateful, binary protocol designed to support distributed objects.

As far as versioning in CORBA, its sounds similar to COM (I’ve done a lot of COM/DCOM programming, but not CORBA), where a published interface is immutable. Its sounds good in practice, but reality has shown it doesn’t work very well. Perhaps you can dismiss this as Microsoft’s incompetence, but I think that’s a simplistic viewpoint. Versioning is a deep, hard problem which I won’t pretend to know anything about. But any distributed system based on interfaces will run right into it.

So I stick to my point that CORBA and REST are fundamentally different - CORBA focuses on services and REST on resources. In my opinion, the focus on resources is in fact something new under the sun.

To finish up, your musing on Haskell/monads/state/HTTP are interesting. HTTP’s statelessness is a good thing (leads to scalability), but dealing with application state (versus resource state) is a pain. Part of the problem is that browsers haven’t provided any infrastructure for managing application state (it belongs on the client), until very recently with the WHATG spec (though kudos to IE for offering some local storage for a long time now). And part of the problem is the cookie spec isn’t very good. But neither are the fault of HTTP.

Anyway, thanks for your thoughts, and I enjoy reading your blog.

Comment on Why Is REST So Hard to Understand? by Samuel A. Falvo II

Thu, 16 Aug 2007 13:07:34 -0600

Wow. I must have had a REALLY bad day yesterday. Although the content wasn’t intended to be offensive, and I still don’t take it as such, I still think I could have worded things a whole lot better. Not only that, but, I completely missed half of what you wrote.

Yes, I am a layerist, because at some point, SOME kind of interface has to exist. Each layer means more software to maintain, which means more bugs. Collapsing the stack is critical to me; my brain can only handle so much.

That being said, I do have some other issues with REST – many compare REST to “what OO should have been” (to paraphrase a page on the restWiki – I can’t remember the link though). I see this as a flawed analogy; OO has always been about not just the data, but what you can do with it. Hence, data and functionality together.

REST is an extension of the bus interface of the CPU – a CPU can read from memory, and write to it. That’s it. Ditto for the Commodore 8-bit Kernals – they were file oriented long before Unix became a household name, and implements an interface that some argue is purer than Plan-9’s. You had only four functions: open, read, write, close. That’s it; literally everything else was done either through tunneling through an overtly documented command channel, or through reading/writing state. Almost RESTful. It only lacked representational standards. Moving one step further, we have the WWW, where RESTful applications are essentially “active RAM.”

I would like to see how security is addressed though. Object capabilities and ACLs both have been demonstrated to be equivalent, but object capabilities are much more scalable (control over individual methods for individual programs for individual users, something which ACLs are absolutely cumbersome at achieving). Yet, except for .htaccess-style ACLs, I can’t see how to map object capabilities to this model. As a result, I see security in a RESTful environment as being a significant challenge – something SOAP and its ilk can implement much more easily.

Thanks.

Comment on Why Is REST So Hard to Understand? by William Tanksley

Fri, 17 Aug 2007 13:24:00 -0600

Object capabilities could be implemented with REST by naming the URI path components according to the HMAC hashes of the names rather than the pure English names.