users@jersey.java.net

[Jersey] Re: Migrating RPC to REST

From: Jason Erickson <jason_at_jasonerickson.com>
Date: Thu, 7 Apr 2011 14:29:20 -0700

So, if we lose the abstract "COMMAND" and use the concrete example of creating a new ORDER, which is essentially a domain-specific command, here we have a resource, ORDER, that we can create, return a link to it in the response, and from that link, retrieve the ORDER, update it, or delete it (identification of resources with URL's, manipulation of the resource through the representation, self-descriptive messages, plus HATEOS unless I'm missing something). But clearly, creating, updating or deleting an ORDER is not an end in itself - you want the system to do something besides just modify the resource. You want to fulfill, change, or cancel the order. Those all change the application state beyond just the state of the resource, but can be fulfilled while, for example, maintaining idempotency of DELETE and PUT and the safety of GET and other key principles of REST.

So I argue that you can implement it in a RESTful way.

However, now that I see the motivation of your question, I will admit that our application violates HATEOS. First, if we have a path ws/obs/meta/phenomenonGroups, it will return all of the phenomenon groups in the application. Good so far. However ws/obs will return a "page" of all of the observations in the system, but no links to the next page. You have to know the allowed query parameters to navigate to other pages, so you have look at our WADL generated documentation. Also, ws/ could return a response with links to ws/obs, ws/users, etc., but it doesn't. It just returns a 405. Similar with other purely "path" URL's like ws/obs/meta. Again, you could figure this out from the WADL generated docs, but that's not the same as being self-documenting. Guilty.

Also, when a resource refers to another resource, (when it is not embedded as part of the object graph) it does so by id, not by the path. I think this is for one reason: Tension between DRY and the Single Responsibility Principle. We didn't want to have some classes for our persistence layer (Hibernate Entities) and a parallel set of classes for the representation (DRY), so we have the JAXB annotations and Hibernate annotations on the same class. This is quite convenient for us, but it does mean that when we don't want to return a whole object graph, we annotate the field for the related object as @XmlTransient and implement a getter for the id. We could instead implement a getter for the path, but these objects are in another layer of the application that is theoretically independent of representation (SRP). So that is probably a failure.

We can take the time to do more, but we have to move fast and we have business pressures to implement features, not architecture, and all the familiar problems everyone else has, so here we are.

If the benefits of RESTful architecture are: performance, scalability, simplicity, modifiability, visibility, portability and reliability, then we have taken the performance, scalability, simplicity and reliability seriously and shortcut the modifiability and portability.


On Apr 7, 2011, at 11:57 AM, Markus Karg wrote:

> Now we come right to the point: Is an application RESTful if it does not transfer STATE but just transfers a COMMAND (i. e. a remote procedure call -- RPC)? Most RESTafarians would say: No, because the COMMAND must be the VERB (not the address or the payload), and there *must* be a transferred STATE (i. e. in this case: an unwanted payload).
>
> Most applications declared to be RESTful (possibly solely due to the fact that they are built ontop of JAX-RS) already omit REST's key principle HATEOS, and we still call them RESTful (are we allowed to do that?). If we now go on and remove STATE transfer (the ST in REST), what is left over from REST? What we then have is an RPC type service using http directly instead of SOAP ("SOAP free http based RPC").
>
> So, does that mean that actually there is no real world application that is actually RESTful? Do we all cheat? Do we actually *want* REST, or do we just want "SOAP free http based RPC plus simplified CRUD support" in JAX-RS? I asked that because I am a JAX-RS 2 EG member an like to know what Jersey users actually do. As it seems, they do not do REST, so maybe JAX-RS should become "Servlet++" instead of REST?
>
> I explicitly ask this question to the Jersey users because I want to know what Jersey users are doing with Jersey and why they think what they are doing is RESTful or couldn't be done with "Servlet++" instead of JAX-RS. The purely philosophical question (how much REST must there be in REST) is clearly defined and to was discussed already at rest-discuss (no HATEOAS no STATE ? no REST !).
>
> What is your opinion?
>
> From: Jason Erickson [mailto:jason_at_jasonerickson.com]
> Sent: Donnerstag, 7. April 2011 00:59
> To: users_at_jersey.java.net
> Subject: [Jersey] Re: Migrating RPC to REST
>
> I would improve this slightly by posting to /my-orders rather than my-shopping-list/new-order, but in my opinion, that doesn't make the example given *not* RESTful, but I think this conversation might benefit from a definition of RESTful. A RESTful web service *usually* is essentially a set of CRUD verbs on a "resource" - the "R" in REST, but according to Wikipedia, to be RESTful, one needs to comply with a set of constraints that don't really require a "resource" in all cases. There are also a set of "Guiding Principals" that seem to require resources to exist in the system, but I wouldn't read it as requiring a resource for every single request, so long as the constraints are still respected.
>
> And if you disallow "commands", which was my abstract version of the more concrete example of an order, are we saying that POST can only create a resource and if it has side-effects (e.g. it starts an order-fulfillment workflow process, or kicks off a stored procedure) then it's no longer a RESTful architecture? In that case, RESTful architectures become quite limited as basically resource repositories. I take REST to be much more flexible than that.
>
> I realize that Wikipedia is not the canonical source, but I don't know what Markus means when he says something is not RESTful.
>
> On Apr 6, 2011, at 3:32 PM, Conal Tuohy wrote:
>
>
> Markus, I think there probably are RESTful solutions to your problem, and I understand you are interested in the general case rather than your particular case (with the stored procedure), but others have already pointed out that you would need to be more specific about the problem (i.e. the domain itself) to elicit those solutions, because, in short, any RESTful solution will need to represent your domain model. So long as the problem is posed in the abstract, or in terms of "running a stored procedure" (which is too low-level) then the business domain remains obscure, yet the domain is the key to formulating a concrete solution.
>
> So I will make up an example:
>
> A supermarket shopper has a shopping list which they can save and reuse. I have one of these with my local supermarket, Coles. Every few weeks I can go on to the Coles website, maybe tweak the list a little, adding an item, removing an item, and then click "Buy Now" which I imagine transfers my shopping list to another list (a "packing list") which someone at the Coles warehouse uses to pack up some cardboard boxes for me.
>
> Is there a RESTful solution to this which doesn't require my browser to download my entire list and re-upload it?
>
> I think there is. I don't need to upload the list, because it is ALREADY there on the server. If my shopping list was linked to an associated resource (an "ordering service") which I could POST to to say "Create a order (from this list) and get packing!", then that would IMHO be perfectly RESTful.
>
> e.g. imagine my shopping list had a representation like so:
>
> GET /my-shopping-list/
>
> <shopping create-order="new-order">
> <item>beans</item>
> <item>milk</item>
> etc.
> </shopping>
>
> Then I could POST
>
> POST /my-shopping-list/new-order
>
> ... and it would create an order from my list, returning me a redirect to: /my-orders/order-3
>
> GET /my-orders/order-3
>
> <order date="2011-04-07" number="3">
> <item>beans</item>
> <item>milk</item>
> etc.
> </order>
>
>
>
> On 06/04/11 21:30, Markus Karg wrote:
>
> Marek,
>
> the intention of the question is a theoretical interest in REST idioms used by Jersey users. There is no technical problem which I would be unable to solve on my own, I just wanted to get an overview of the idioms and patterns used by Jersey users to solve problems like these. So the discussion is not: "Why to do REST?" as doing REST is the given constant in this paradigma.
>
> I want to find out whether there is a common sense (pattern or idiom) among the Jersey users for solving any member of this class of problems ("copying data inside of the server without GETting it first and PUTting it later"). The problem is common and not tied to one particular, actual business domain use case.
>
> As Jan correctly pointed out, without any transfer, it wouldn't be RESTful by definition. So the end of the discussion is reached obviously: There cannot exist a valid solution, since REST *must* forward the representational state (a command, in any form, is not a representational state).
>
> To sum up:
>
> In WebDAV, COPY is the best technical approach, but it is not RESTful.
>
> In pure HTTP, PUT with some kind of additional source URL would be the best technical approach, but it is not RESTful.
>
> To be RESTful, the source object *must* get transferred by definition, so in this class of problems, it must get copied twice. With REST applied to http this means, GET and PUT of an unchanged object. A technical help for performance is using a caching proxy most near to the client to at least prevent a GET content transfer over the whole web. AFAIK a PUT cannot be optimized in that way as it must not store into a cache (maybe I am wrong with that).
>
> So now I know what I wanted to know: There cannot be a RESTful solution. If it must be RESTful, then it *must* copy the source twice over the LAN.
>
> Thanks to all participiants. :-)
>
> Regards
> Markus
>
> -----Original Message-----
> From: Marek Potociar [mailto:marek.potociar_at_oracle.com]
> Sent: Mittwoch, 6. April 2011 12:03
> To: users_at_jersey.java.net
> Cc: Markus Karg; 'Arthur Yeo'
> Subject: [Jersey] Re: Migrating RPC to REST
>
> Hi Markus,
>
> Have you considered to actually NOT replacing this stored procedure call with RESTful architecture? Perhaps I am missing
> some important piece of information from your use case, yet from what was discussed here it seems to me that in this
> case RCP-style call may be actually more suitable for your use case.
>
> What features of the RESTful architecture do you want to leverage in this use case (scalability, cacheability, loose
> coupling, transparency ...)? IOW, why do you want to expose the stored procedure in a RESTful way?
>
> Marek
>
> P.S. I agree with what Jan wrote earlier - if you really need to redesign this use case in a RESTful way, you need to
> look at the operation as a (temporal) service resource in the context of it's domain. Then you might be able to properly
> define the resource including the URI scheme, HTTP operations and payloads etc. It is however difficult to make concrete
> proposal based on the "INSERT FROM SELECT" information :)
>
> On 04/05/2011 10:46 PM, Markus Karg wrote:
> You're right, but that doesn't solve the problem that your proposal is not RESTful: A PUT must provide the source entity
> as a body. How will you provide the URL of the source without breaking the rules of RESTfulness? See, the question was
> not "How to call a stored procedure using http?" but "How to call a stored procedure in a RESTful way?".
>
>
>
> Regards
>
> Markus
>
>
>
> *From:*Arthur Yeo [mailto:artyyeo_at_gmail.com]
> *Sent:* Dienstag, 5. April 2011 20:00
> *To:* users_at_jersey.java.net
> *Cc:* Markus Karg
> *Subject:* Re: [Jersey] Re: Migrating RPC to REST
>
>
>
> If the URL species the PK of the INSERT, which I take it to mean the unique ID for the new rsrc, then you should be
> using a PUT instead of a POST.
>
> On Tue, Apr 5, 2011 at 10:52 AM, Markus Karg<markus.karg_at_gmx.net<mailto:markus.karg_at_gmx.net>> wrote:
>
> Arthur,
>
>
>
> there is one thing you are missing: How to tell POST where to take the data from (i. e. the PK used in the WHERE clause
> of the SELECT)? Obviously you need to pass it as some kind of header with the POST (the URL of the POST is the PK of the
> INSERT, not the PK of the SELECT). So it is not RESTful, as Jan pointed out this afternoon already.
>
>
>
> Regards
>
> Markus
>
>
>
> *From:*Arthur Yeo [mailto:artyyeo_at_gmail.com<mailto:artyyeo_at_gmail.com>]
>
> *Sent:* Dienstag, 5. April 2011 19:24
> *To:* Markus Karg
>
> *Cc:* users_at_jersey.java.net<mailto:users_at_jersey.java.net>
>
>
> *Subject:* Re: [Jersey] Re: Migrating RPC to REST
>
>
>
> If the data is self-generated within the sproc from a SELECT and the sproc is using that data to do an INSERT, I do not
> see a reason to put anything in the POST, not unless you have some params.
>
>
>
> You are creating a new resource with your POST which is carried out by your original sproc. There is no payload in the
> POST for this case.
>
> Your POST, in this case, is even lighter weight than ordinary POST that has a payload.
>
> You did not change the meaning of a POST. Just make sure you return some kind of identification back to the frontend for
> the creation of that new rsrc.
>
>
>
> On Tue, Apr 5, 2011 at 10:11 AM, Markus Karg<markus.karg_at_gmx.net<mailto:markus.karg_at_gmx.net>> wrote:
>
> Arthur,
>
>
>
> if you want to do a POST, what actually do you like to send as the body? As Jan correctly pointed out, sending an empty
> body is not RESTful.
>
>
>
> Regards
>
> Markus
>
>
>
> *From:*Arthur Yeo [mailto:artyyeo_at_gmail.com<mailto:artyyeo_at_gmail.com>]
> *Sent:* Dienstag, 5. April 2011 18:59
> *To:* users_at_jersey.java.net<mailto:users_at_jersey.java.net>
> *Cc:* Markus Karg
> *Subject:* Re: [Jersey] Re: Migrating RPC to REST
>
>
>
> Then, I am not understanding your concerns.
>
> If there's already an sproc to do an INSERT based on some SELECT, all you have to do is to either do a POST/PUT over
> JDBC to call that sproc, depending on your application's needs.
>
> I do not see how the data is is moved twice? Please elaborate.
>
>
>
> On Tue, Apr 5, 2011 at 9:45 AM, Markus Karg<markus.karg_at_gmx.net<mailto:markus.karg_at_gmx.net>> wrote:
>
> I never said that I want to break up the INSERT FROM SELECT. In fact I still
> want to call the stored procedure. But I want to discuss a possibly RESTful
> interface for calling a stored procedure.
>
> -----Original Message-----
> From: Arthur Yeo [mailto:artyyeo_at_gmail.com<mailto:artyyeo_at_gmail.com>]
> Sent: Dienstag, 5. April 2011 16:50
> To: users_at_jersey.java.net<mailto:users_at_jersey.java.net>
> Subject: [Jersey] Re: Migrating RPC to REST
>
> Is there a reason why you have to break up the INSERT and SELECT? I
> thot u said these are all handled in a sproc?
>
>
>
> On Tuesday, April 5, 2011, Markus Karg<karg_at_quipsy.de<mailto:karg_at_quipsy.de>> wrote:
> Hello Jersey Community, we're in the process of migrating some
> functionality from RPC to REST and stuck with an issue we'd like to
> discuss with you. :-) One of the business procedures we're migrating
> was implemented as a stored procedure. It actually did nothing special
> but just provided a copy of a rather big amount of records in a single
> transaction. You can think of it in terms of SQL as "INSERT FROM
> SELECT". In JAX-WS's RPC style it was just wrapped with a method of a
> @WebService that called the stored procedure. But how to convert this
> to a RESTful style in JAX-RS? Our initial idea was to do a http GET to
> load the source, then forward that same XML body to a http POST.
> Obviously that is RESTful and simple to do, but it means moving a
> really, really big bunch of information twice over the web, just for
> the sake of RESTfulness (and it would be two transactions, obviously).
> Has anybody an idea how to RESTfully model this use case, so that the
> data is not transferred at all but we still can just call the existing
> stored procedure? The only idea we had would be doing RPC style, like
> http post with a Location-header pointing to the source. But obviously
> that is not very RESTful. Any ideas? :-) RegardsMarkus
>
> --
> Arthur Y.
>
>
>
> --
> Arthur Y.
>
>
>
>
> --
> Arthur Y.
>
>
>
>
> --
> Arthur Y.
>
>
>
> --
> Conal Tuohy
> eResearch Business Analyst
> Victorian eResearch Strategic Initiative
> +61-466324297
>
>