> I suspect that those two camps started when architects/programmers
> began using the technology in the real world, beyond samples. I doubt
> every RESTafarian would regard REST APIs such as Sun Cloud, Flickr,
> etc. as pure REST. Perhaps this is due to one camp not communicating
> well with the other (lack of a best practices document?); perhaps this
> is simply an evolution of the technology.
And I suspect that people too often do not try to understand what the
original inventor wanted to say and just do something different and name
that REST. Remember why Fielding wrote the dissertation: He had the thesis
that REST is working since the WWW is working. If you start to do something
different the you would foil his thesis actually, since you would doubt that
the WWW *can* be working... How ever did all those millions of web sites
work without sending links in headers...?! ;-)
> Of course, we don't want the technology to morph into something that
> it isn't, hence the importance of these discussions! As Paul has
> stated, I think it's important to bring this discussion down to real
> problem solving and real prototypes and running examples. This will
> simplify communication between the two camps.
I think the problem is the opposite: We are discussing things that just are
not REST, while our job actually is to define a Java API for REST. So we
cannot discuss the example, as it is not RESTful. It wouldn't make sense. We
all are graduated, so we should be possible to discuss abstract application
architecture without the need to discuss particular use cases. Shouldn't we?
I mean, Fielding described HATEOAS without showing screenshots of web sites,
so we should be able to just apply his descriptions without the need to have
a definitive use case.
> Let's look at the purchase order example again. Let's say I have 300-
> field order, which is not uncommon in real examples.
If it is not common, why using it as an example then?
> If the only way a
> client can affect the application state is by PUTting a new
> representation of this order, then the implementation of this system
> can get quite hairy.
> If there are N states and M fields in the order
> that can trigger those N states, then (i) the client needs to send a
> complete order (even if only one field is updated) and (ii) the server
> needs to compare and analyze the new representation against the
> existing one to determine the transition. This may be "pure" REST for
> some, but practical it isn't. Wouldn't it be easier to hint the server
> about what's going on?
The example is wrong. Why do you want to upload the order while the client
actually still is adding items? And why do you want to have items be part of
the order instead of each being its own resource instance (Fielding also
told us to not build aggregates where references will server pretty well).
As long as the client is in the process of adding items, the state of the
workflow is not changing. So why pushing something up to the server? For
what?
Do you see what I mean with "the example is not the problem, since it is not
RESTful"?
> So PATCH was invented for partial updates ...
Your softeware is getting quirky... Just wait with the upload until the
client is done.
> even though Roy himself
> said it's OK to use POST in those cases [1]. If there are fields in the
> representations that can be used to trigger state changes, then PATCH
> may work.
You misunderstood what "state" means. "state" is not content. It is modified
by content. As long as you are adding items to the order, "state" is
unchanged. It was "ADDING_ITEMS" before you added the first, and it still is
"ADDING_ITEMS" until you're done with the 300th. You could THEN upload the
complete order once, and the server will modify the state of the document
for example to "REGISTERED_FOR_SHIPPING". Notice that you did neither have
to know an action for that, nor to use a header. The server recognized the
state change automatically since you would not upload the order unless your
finished (implied).
> But as Tim pointed out [2], in some cases, you're really
> asking for some action (what Tim and Roy refer to as buttons in their
> blogs) to be carried out, perhaps even asynchronously, that does not
> quite map to a client representation change.
There is no problem in making the server do anything as a reaction to a PUT,
as you only have one PUT. Remember, you have no need to upload the order
unless it contains all 300 items. Does a HTML form get uploaded unless all
300 input fields are filles out? NOPE! So why wanting to do so?
> I don't think these
> buttons/actions make any system more or less REST (although I perfectly
> understand how they can trigger these long discussions :)
Well, as I tried to point out in my blog, the definition of REST is
(luckily) not dependent on what your or me or anybody THINKs, as there is
exactly one and only one exact and unambiguous defition given in the
dissertation by Mr Fielding. And that definition does not contain actions or
buttons, so they are NOT RESTful. If you still doubt it, read Fielding's
blog
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
that points out that actions of any form are NOT RESTful as they are RPC.
Regards
Markus