Hypermedia Support is useless

From: Markus Karg <>
Date: Sun, 14 Feb 2010 09:20:40 +0100

Sorry for commenting so late, but I did not find the time earlier.


I read the proposed API for hypermedia support
#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

    Pay: POST http://.../orders/1/ @Consumes xml/cheque @Produces

    Ship: PUT http://.../orders/1/ @Consumes xml/shippingOrder @Produces


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.