Menu
▾
▴
resteasy-users
|
From: J C. <jc...@su...> - 2014-01-27 02:44:50
|
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. |
|
From: J C. <jc...@su...> - 2014-02-28 15:18:37
|
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 <jc...@su...>
To: res...@li...
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.
|
|
From: Bill B. <bb...@re...> - 2014-02-28 15:37:25
|
"Mr. Burke" lol...my kid's friends don't even call me that. :) Thanks
for the writeup.
On 2/28/2014 9:14 AM, J Coder wrote:
> 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 <jc...@su...>
> To: res...@li...
> 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
> Res...@li...
> https://lists.sourceforge.net/lists/listinfo/resteasy-users
>
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com
|
Thanks for helping keep SourceForge clean.
X