Markus,
On Feb 14, 2010, at 9:20 AM, Markus Karg wrote:
> Sorry for commenting so late, but I did not find the time earlier.
>
> I read the proposed API for hypermedia support https://jersey.dev.java.net/nonav/documentation/1.2-SNAPSHOT/user-guide.html#d4e1013 and liked to share my comments.
>
> Chapter 5 "Hypermedia" explains a new API proposal for an allegedly unsupported part of Roy Fieldings' thesis, HATEOAS. The chapter uses an example of a workflow that allegedly is badly supported in JAX-RS so far:
> • checking the customer's credit status
> • reserving product inventory
> • verifying per-customer quantity limits.
> Also the document explains that a proposed API will "solve" the problem by supporting "action resources":
>
> Review: POST http://.../orders/1/review
> Pay: POST http://.../orders/1/pay
> Ship: PUT http://.../orders/1/ship
>
> Thinking several time over the alleged problem, I came to my personal conclusion that either you or me did not understand that JAX-RS handles this perfectly already, or I did not understand the problem itself, or maybe the example workflow is just too simple.
Glad you raise that issue, too. I am also not seeing what problem the proposal is trying to solve.
Even *if* the approach to, for example, starting a review process was the best way to go, I am notseeing why the client code should not simply extract the link from the response and create the next request. I find the proposal confusing because I do not see what the problem is.
> Let me explain:
>
> A real RESTful application needs no actions to solve workflows like the above. In the real world, if a company lives that workflow and has no computers, they will forward paper documents: Review Orders, Review Results, Cheques, Receipts, Shipping Orders, Delivery Notes.
Exactly. We should all emphazise (business-) document orientation and not focus on mappiing actions to links to pretend its RESTful.
> [...]
> The only difference is: The proposed new API is everything but RESTful! It is a rape of the RESTful idea by people wanting to enforce a RPC-style API ontop of REST
Instead, the client programer should *see* the network guts - as ugly as they may be. order.review() hides that we are dealing with remote calls
> -- but REST rest is about documents, not about methods (I am trying to make this clear every day). It just makes no sense to directly map command verbs to URLs in REST. If you like to do that, go to SOAP. Also, the proposed API is less readable for people knowing the paper process,
Very much agree.
> on both, the Java level (since it now implies command verbs where the paper process had none and was solely based on transferring representational state: Documents!) and the wire level. In fact I wonder where REST is in you proposal? I do not see any representational state getting transfered anymore, since many of the example methods void-in or void-out or even both!
Yes.
I am not sure, of course, but it seems sometimes people take the hypermedia constraint to the extreme by very explicitly modeling the state transition aspect (mapping actions to links) where submissions of documents to processing resource would just do the job and be more naturally align with the paper process (as you said).
>
> Guys, that has nothing to do with REST. You just try to do RPC with http. If you really like to implement that, then please remove the "R" from the API's name, since that is not REST anymore.
Jan
>
> Regards
> Markus
-----------------------------------
Jan Algermissen, Consultant
NORD Software Consulting
Mail: algermissen_at_acm.org
Blog:
http://www.nordsc.com/blog/
Work:
http://www.nordsc.com/
-----------------------------------