Mr. Burke and I had a conversation that stemmed from this question but it never 
made it's way onto the mailing list. I've summarized the discussion and I'm 
posting it here so others can benefit from his wisdom.

J

-------------------------------------------------------------------------------

From: Coder

I do have a follow up question if you have a few more moments. If not, I 
understand. I don't want to monopolize too much of your time.

> I'm saying that GET /cars/honda would return a reprsentation that had
> links to the actions. Then the client knows which URL to invoke from
> the representation of the car instead of having to know the URL scheme.

This makes sense, but I have a question about this approach. Since this saves 
the client from needing to know the URL scheme beyond the basic resource 
retrieval, I have to assume that the same concept extends to required 
parameters and possible values, otherwise, saving the client from needing to 
know the scheme isn't 'full serve'.

So, given this URL that would have come back as a copy action from the original 
GET /file/{file_id}:

> POST /file/{file_id}/copy
> Content-Type: application/json
>
> {
> "from" : "dir1",
> "to" : "dir2"
> }

Where would the information for the from and to parameters, plus the potential 
dir values come from? Would those be something that would have come back from a 
different call that is perhaps associated to the form (or client interface), 
rather than to the individual resource that was retrieved? Perhaps it depends 
on the application context?

Thanks!

J

-------------------------------------------------------------------------------

From: Burke

> I see. So, in your example, a representation of an assembled honda might be 
> returned by a call to POST /cars/honda/assemble?

I'm saying that GET /cars/honda would return a reprsentation that had links to 
the actions. Then the client knows which URL to invoke from the representation 
of the car instead of having to know the URL scheme.

> In my case, I want to perform a file copy based on a file ID (internal 
> representation), so I might do a call like POST 
> /file/{file_id}/copy?from=dir1&to=dir2 and the result might be:

Query parameters should be attributes of a resource only, not parameters for an 
action. Parameters for an action should be encapsulated in a representation:

POST /file/{file_id}/copy
Content-Type: application/json

{
   "from" : "dir1",
   "to" : "dir2"
}

Response:

201
Location: /file/new-copy-id

The above doesn't have to be json. Form params are fine too.

URLs should always point to something that is linkable. In your example, 
/file/{file_id}/copy?from=dir1&to=dir2 is not a linkable thing because it 
contains parameters of an action.

>
> {
> "file": {
> "file_id": "8477KSHIU88",
> "locations": {
> "location": [
> {
> "name": "dir1",
> "value": "/dirs/dir1/1.2.3.txt"
> },
> {
> "name": "dir2",
> "value": "/dirs/dir2/1.2.3.txt"
> }
> ]
> }
> }
> }
>
> This output might be the same as a call to GET /file/{file_id}
>
> Am I getting the general idea?

You don't have to return the result, just a URL to it if you've created a new 
resource. Not sure I understand your example enough to know if you have.

Honestly though, IMO, just do what's simplest to both implement and for clients 
to consume. Just stay away from adding new HTTP methods or embedding actions 
within Query parameters (JAX-RS can only dispatch by path).

-------------------------------------------------------------------------------

From: Coder

I see. So, in your example, a representation of an assembled honda might be 
returned by a call to POST /cars/honda/assemble? In my case, I want to perform 
a file copy based on a file ID (internal representation), so I might do a call 
like POST /file/{file_id}/copy?from=dir1&to=dir2 and the result might be:
{
   "file": {
      "file_id": "8477KSHIU88",
      "locations": {
         "location": [
         {
            "name": "dir1",
            "value": "/dirs/dir1/1.2.3.txt"
         },
         {
            "name": "dir2",
            "value": "/dirs/dir2/1.2.3.txt"
         }
         ]
      }
   }
}

This output might be the same as a call to GET /file/{file_id}

Am I getting the general idea?

J

-------------------------------------------------------------------------------

From: Burke

If you have a representation for the action, then it becomes a resource that 
you could possibly link to and retrieve. It becomes even more important to 
represent the action as a URL as you can then link to the action:

{
   "car" : "honda",
   links : {
      "assemble" : "/cars/honda/assemble"
   }
}

The client then never has to know the URL scheme, only the data format.

-------------------------------------------------------------------------------

From: Coder

Understood. It adds no value to extend a concept if some implementations can't 
make use of it.

I struggle with the concept of putting the action in the URL because I have a 
hard time opening my mind to the idea of 'an action is a resource'. Hard for me 
to let go of the 'R' in URL in other words.

If this is the defacto approach however, it makes sense to give client 
developers what they expect so it remains consistent and intuitive.

Much thanks for your time, Bill. The advice is appreciated.

J

-------------------------------------------------------------------------------

From: Burke

I don't suggest that approach. Instead, put the action in the URL.

i.e.

POST /cars/honda/assemble
Content-Type: application/work-order+json

Some clients or servers and/or their APIs might have issues dealing with 
non-standard HTTP methods. Plus HTTP methods have well defined semantics that 
client developers will expect to be followed. i.e. PUT/GET/DELETE is supposed 
to be idempotent.

-------------------------------------------------------------------------------

From: Coder

Wonderful! Thank you very much, this is exactly what I was hoping for. I was 
incorrectly assuming that the method had to be annotated with one of the 
pre-defined values. I am not sold, in general, on the idea of either treating 
resources as actions or as passing actions in as parameters, so this gives a 
very nice option. I suppose it should have occurred to me that I could just 
create a new annotation...

Thanks,

J

-------------------------------------------------------------------------------

From: Burke

By extension-method you mean something like PATCH? Yes, JAX-RS supports
that

@HttpMethod("PATCH")
public @interface PATCH{}

-------------------------------------------------------------------------------

From: Coder

Can this be done?

Similar to how WebDAV has PROPFIND, MOVE and COPY in addition to the standard 
GET, POST, DELETE and such.

If so, a pointer to an example would be much appreciated. 




----- Original Message -----
From: J Coder <jco...@superheromail.com>
To: resteasy-users@lists.sourceforge.net
Sent: Tuesday, January 28, 2014 09:48 AM
Subject: [Resteasy-users] Can JAX-RS support an extension-method?

Can this be done?

Similar to how WebDAV has PROPFIND, MOVE and COPY in addition to the standard 
GET, POST, DELETE and such.

If so, a pointer to an example would be much appreciated.






------------------------------------------------------------------------------
Flow-based real-time traffic analytics software. Cisco certified tool.
Monitor traffic, SLAs, QoS, Medianet, WAAS etc. with NetFlow Analyzer
Customize your own dashboards, set traffic alerts and generate reports.
Network behavioral analysis & security monitoring. All-in-one tool.
http://pubads.g.doubleclick.net/gampad/clk?id=126839071&iu=/4140/ostg.clktrk
_______________________________________________
Resteasy-users mailing list
Resteasy-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/resteasy-users

Reply via email to