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:
1. checking the customer's credit status
2. reserving product inventory
3. 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. 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. In fact, due to
usefulness, custom and legal / tax / customs regulations, they actually have
to archive those documents for several years. So when replacing the paper
process by an electronic process, you typically won't change the process or
it's parameters (the documents), but just immitate it in an electronic form:
Replacing the paper documents by XML documents. If you would apply the
RESTful pattern, you will come to the following API by a simple 1:1 mapping
of paper to electronic form:
Review: POST
http://.../orders/1/ @Consumes xml/reviewOrder @Produces
xml/reviewResult
Pay: POST
http://.../orders/1/ @Consumes xml/cheque @Produces
xml/receipt
Ship: PUT
http://.../orders/1/ @Consumes xml/shippingOrder @Produces
xml/deliveryNote
This is absolutely HATEOAS and exemplary RESTful! JAX-RS already can map it
directly without any problem. Also it is in fact readable to everybody
understanding the paper process, and if you look carefully you will notice
that it actually is nearly the same wire-level API that is produces by your
proposed "solution".
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 -- 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, 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!
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.
Regards
Markus