How RESTful is RestDataSource/RESTHandler?

[cowboy.coder.killer]

My experience is mostly in enterprise integration/SOA type projects [meaning: non-public APIs]. I'm mainly a dyed-in-the-wool SOAP/WS* guy myself. I've only become interested in the formal ReST architectural style in the last 2 weeks.

But I'm always up for learning new stuff. So in the recent few days of researching the whole ReST bandwagon, I think I now grok Chapter 5 of Roy Fielding's PhD dissertation well-enough to at least be able to ask some salient questions.

A lot of what I've read about ReST makes me reminisce about the PERL/CGI work I use to do back in the day. But I digress.

What I need to ask at this point in my learning about ReST [and SmartGWT's take on it], is this...

1. To which of Fielding's original ReSTful constraints does RestDataSource and RESTHandler conform?
2. If RestDataSource/RESTHandler do not conform to the "Pure ReST" style [as defined by Fielding], what are the practical reasons for Isomorphic not doing so?
3. Why does it seem like SmartGWT's "RestXXX" components are simply piggybacking on the ReST buzzword, while not being strictly ReSTful?
4. Why wouldn't HttpMessageDataSource and HttpMessageHandler be more apt names for RestDataSource and RESTHandler respectively?

My questions are not targeted at Isomorphic exclusively. I'd be equally grateful for anybody else's answers based on their experience using RestDataSource/RESTHandler with their purely ReSTful services. Thank you in advance.

[Isomorphic]

RestDataSource departs from Fielding's early conception in two main ways:

1. queuing is designed to allow multiple logical requests in one HttpRequest, to allow the server to implement multiple requests in a transaction. This means we can't use distinct URLs or distinct HTTP verbs for different operation types and we can't put a resource identifier into the URL either

2. even if you don't use queuing (which we consider a major mistake), we still recommend against using the GET HTTP verb for fetches:

Using dataProtocol:"getParams" for "fetch" operations that involve complex AdvancedCriteria will result in a JSON serialization of the AdvancedCriteria in the request URL, and when combined with large cookies this can easily overflow the default limits on certain webservers (see http://stackoverflow.com/questions/686217/maximum-on-http-header-values). For this reason, we recommend that you use the "postMessage" protocol whenever you are intending to use AdvancedCriteria with RestDataSource.

RestDataSource *can* be easily configured to strictly conform to Fielding's original concept of REST, but it's not the default since you'll lose a lot of key features which cannot be implemented in that model.

[Isomorphic]

It seems like we'd better state explicitly, again: we strongly, strongly strongly recommend against configuring RestDataSource in a way that breaks queuing (distinct URLs per request/operationType etc).

Several times we've seen projects decide that queuing is an edge case, not implement it, then run into a nasty surprise when they try to enable one of dozens of features that needs queuing to work: mass update (listGrid.autoSaveEdits:false), multi-row drag&drop, BatchUploader, large tree load-on-demand, master-detail saves, serverCustom validators, CubeGrid, many others.

When you follow best practices, enabling these features is a trivial setting, when you ignore best practices, you are usually in a "train wreck" situation because the best course correction is to go back and rework the REST implementation you thought was done, and that's a hard pill to swallow, so people try to hack around the lack of queuing with bespoke implementations of built-in framework features, and those bespoke implementation are tough to get right and don't quite work..

Anyway don't be a train wreck :)

[cowboy.coder.killer]

That's Telling...

...
Several times we've seen projects decide that queuing is an edge case, not implement it, then run into a nasty surprise when they try to enable one of dozens of features that needs queuing to work: mass update (listGrid.autoSaveEdits:false), multi-row drag&drop, BatchUploader, large tree load-on-demand, master-detail saves, serverCustom validators, CubeGrid, many others...

No disrespect. But that sounds like several of your own paid-for-support customers are also missing something obvious ;)

[Isomorphic]

Yes.

It's the rare project, paid Support or otherwise, that hasn't missed something important that is thoroughly covered in the QuickStart, FAQ, etc.

We are constantly revising the materials to try to prevent the most common and most damaging missteps. But the fact is, there are many mistakes that can be made, and not everything can be placed in bold blinking red text at the top of the intro materials.

Note to mention that, even if it were possible to force all warnings to be read and considered, many people are simply headstrong.

[cowboy.coder.killer]

The Principle Of The Thing...

...then run into a nasty surprise when they try to enable one of dozens of features that needs queuing to work...

For me, the word surprise is a synonym for astonishment. You have this surprising "feature" of a component with the "ReST" buzzword in its name. The surprise is, that component penalizes "pure ReSTful API" developers for using distinct URIs [for distinct resources] and for using GET to fetch those distinct resources. To me, that sounds like a framework design that violates The Principle of Least Astonishment...

Principle of least astonishment

...[When elements] of an interface conflict, or are ambiguous, the behavior should be that which will least surprise the user; in particular a [framework designer] should try to think of the behavior that will least surprise someone who uses the [framework], rather than that behavior that is natural from knowing the inner workings of the [framework]...

[more]

Don't get me wrong. I'm very impressed with SmartGWT — in general. It's apparent from your and your colleagues' posts, that you guys are very, very smart dudes and dudettes :thumbsup:

I'm just expressing my technical opinion that your "REST" components seem inconsistent with my two week old — admittedly naive — expectation of how a so-called ReSTful framework might be hooked into.

If I myself had designed something exactly like what we're talking about in this thread, I would have named the components something like "HTTPMessageDataSource" and "HTTPMessageHandler". Because when you boil them down to their essence, sending messages over HTTP is pretty much the core [or "default"] functionality of what we're talking about here. Any real ReSTfulness seems to be a way lower-significance, played-down feature. That being the case, then I would provide a simple, inconspicuous isRESTLike flag on my HTTPMessageXXX components to offer the least-preferred option to work in a "Kind-of ReST-like" messaging style.

That way, developers wanting to hook into my more honestly-named "HTTPMessageXXX" components would not be mislead into expecting they could wire their pure ReSTful APIs straightforwardly into my framework — with no surprises. Otherwise — if I bill a component as ReSTful — then naturally people are going to be astonished when they find out [after the inevitable "train-wreck"] that they have to now (re)write a whole new, non-reusable, special-case interface to their existing services/resources, just to be compatible with my buzzword-inspired, misleadingly-named, proprietary messaging protocol.

But hey! Whatever works. Right? :¬)

[Isomorphic]

It's great that you've done some background reading on where the term REST originally came from, but the reality is that most developers use the term REST to mean anything that passes JSON or XML over HTTP and isn't WSDL.

That common usage is basically the end of the discussion as far as what RestDataSource should be named. If RestDataSource were named something else, we would have a bunch of posts about "I want to use REST, why isn't there a class for that, why do I have to use HttpMessageHandler when I want REST?".

There's really no need for a further reason for the name, but it's also the case that RestDataSource is the class to use for strict REST, and has no default settings that conflict with strict REST, so it's also correct name even if the strict notion of REST is the only one that someone has learned.

Finally, this:

that component penalizes "pure ReSTful API" developers

.. is incorrect.

There is no way to do mixed operation transactions and follow strict REST. This isn't a design choice by us, it's just a fundamental part of HTTP. It's absurd to say we or the component is "penalizing" people; an accurate statement is that RestDataSource makes it possible to address use cases strict REST doesn't handle.