"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 <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
>
--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com
------------------------------------------------------------------------------
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
