Quantcast

Initial Draft: Grails 2.3 REST updates

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
36 messages Options
12
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Initial Draft: Grails 2.3 REST updates

Graeme Rocher-2
Hi all,

I've put together a rough initial draft of the REST improvements that are to go into 2.3:


This is request for feedback and ideas. There is also this top level JIRA issue


Feedback will help flesh out the ideas further and make sure we have a more complete solution

Thoughts appreciated

--
Graeme Rocher
Grails Project Lead
SpringSource
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

bobbywarner
What are people's thoughts on "nested resources" for collections?

class Author {
  static hasMany = [books: Book]
}

"/authors"(resources: 'author') {
  "/books"(resources: 'book')
}

GET: /authors/1/books
GET: /authors/1/books/create
POST: /authors/1/books
GET: /authors/1/books/1
GET: /authors/1/books/1/edit
PUT: /authors/1/books/1
DELETE: /authors/1/books/1


Should I add it to the wiki page?  Let me know!


Thanks,
Bobby
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

cdeszaq
In reply to this post by Graeme Rocher-2
Overall, the improvements look good, and will be a very welcome set of built-in capabilities! Below are some thoughts:

Being able to have code that runs async when the data call returns is great, but it would be even better if the data calls could return promises instead. This has lots of benefits, including keeping the controller less aware of how the data gets to it, as well as decoupling the code that uses the data from the call itself. I realize that this might not jive with how Grails currently does Async stuff, but figured it couldn't hurt to toss it in as an idea. (I didn't explain this very well, but I hope it's still understandable)

The marshaller / unmarshaller in the mapping section is a good idea. Fairly simple, yet quite powerful, but the example only has a single field. Does the marshaling have to handle all fields, or is it possible to only specify "overrides" on specific fields and leave the rest to be handled by the defaults? Also, how does the marshal / unmarshal handle relationships between domain classes?

In fact, this seems to be the biggest missing piece: How will relationships between domain classes be handled? A set of examples that go through the vision of how the relationships will be handled would be great.

Thanks,
Rick (cdeszaq) Jensen


On Thu, May 2, 2013 at 5:20 AM, Graeme Rocher <[hidden email]> wrote:
Hi all,

I've put together a rough initial draft of the REST improvements that are to go into 2.3:


This is request for feedback and ideas. There is also this top level JIRA issue


Feedback will help flesh out the ideas further and make sure we have a more complete solution

Thoughts appreciated

--
Graeme Rocher
Grails Project Lead
SpringSource

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

cdeszaq
In reply to this post by bobbywarner
Re: Nested Resources:

I think that way of handling nested resources would be great. We're already doing something along those lines (albeit not quite as elegantly) with a number of applications, so I would say that this makes sense to include in the wiki.

Is it safe to assume that such a way of specifying nested resources would allow for arbitrary depth?
Is it also safe to assume that those URLs would not preclude having /books/ as a top-level resource as well?

One thing that isn't clear is how, in this case, would the requests map to controllers/actions. I think my preference would be that the request would map to the lowest-level (ie. the deepest child) resource's controller, and for there to be a way for the receiving action to be able to determine the "path" that was used to get to that resource. The idea being that /authors/1/books would map to Book.index() and that action would be able to list the books for the author from the URL path. Though, I could see the other-way-around working too, but I'm not sure how well either way would hold up to arbitrarily deep nestings.

This is a fairly complex chunk of behavior, so additional discussion is most welcome! I think nested resources is important to have, but the details are still very hazy.

Thanks,
Rick


On Thu, May 2, 2013 at 9:48 AM, bobbywarner <[hidden email]> wrote:
What are people's thoughts on "nested resources" for collections?

class Author {
  static hasMany = [books: Book]
}

"/authors"(resources: 'author') {
  "/books"(resources: 'book')
}

GET: /authors/1/books
GET: /authors/1/books/create
POST: /authors/1/books
GET: /authors/1/books/1
GET: /authors/1/books/1/edit
PUT: /authors/1/books/1
DELETE: /authors/1/books/1


Should I add it to the wiki page?  Let me know!


Thanks,
Bobby



--
View this message in context: http://grails.1312388.n4.nabble.com/Initial-Draft-Grails-2-3-REST-updates-tp4644188p4644200.html
Sent from the Grails - dev mailing list archive at Nabble.com.

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Graeme Rocher-2
In reply to this post by bobbywarner
Hi Bobby,

Yes nested resources are on the todo list as well

Cheers


On Thu, May 2, 2013 at 4:48 PM, bobbywarner <[hidden email]> wrote:
What are people's thoughts on "nested resources" for collections?

class Author {
  static hasMany = [books: Book]
}

"/authors"(resources: 'author') {
  "/books"(resources: 'book')
}

GET: /authors/1/books
GET: /authors/1/books/create
POST: /authors/1/books
GET: /authors/1/books/1
GET: /authors/1/books/1/edit
PUT: /authors/1/books/1
DELETE: /authors/1/books/1


Should I add it to the wiki page?  Let me know!


Thanks,
Bobby



--
View this message in context: http://grails.1312388.n4.nabble.com/Initial-Draft-Grails-2-3-REST-updates-tp4644188p4644200.html
Sent from the Grails - dev mailing list archive at Nabble.com.

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email





--
Graeme Rocher
Grails Project Lead
SpringSource
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Graeme Rocher-2
In reply to this post by cdeszaq
Answers below.


On Thu, May 2, 2013 at 5:28 PM, Rick Jensen <[hidden email]> wrote:
Overall, the improvements look good, and will be a very welcome set of built-in capabilities! Below are some thoughts:

Being able to have code that runs async when the data call returns is great, but it would be even better if the data calls could return promises instead. This has lots of benefits, including keeping the controller less aware of how the data gets to it, as well as decoupling the code that uses the data from the call itself. I realize that this might not jive with how Grails currently does Async stuff, but figured it couldn't hurt to toss it in as an idea. (I didn't explain this very well, but I hope it's still understandable)

The marshaller / unmarshaller in the mapping section is a good idea. Fairly simple, yet quite powerful, but the example only has a single field. Does the marshaling have to handle all fields, or is it possible to only specify "overrides" on specific fields and leave the rest to be handled by the defaults? Also, how does the marshal / unmarshal handle relationships between domain classes?

Yes if you only want to include or exclude certain fields then we'll have a mechanism to do that. I will write up something in the doc
 

In fact, this seems to be the biggest missing piece: How will relationships between domain classes be handled? A set of examples that go through the vision of how the relationships will be handled would be great.

For relationships we will probably add a way to render atom links. For example:

<person xmlns:atom="http://www.w3.org/2005/Atom">
  <firstname>Dave</firstname>
  <lastname>Matthews</lastname>
  <links>
    <atom:link rel="books" href="http://myhost/books" />
  </links>
</person>

Otherwise rendering a list of associated ids or the id is possible as well

 

Thanks,
Rick (cdeszaq) Jensen


On Thu, May 2, 2013 at 5:20 AM, Graeme Rocher <[hidden email]> wrote:
Hi all,

I've put together a rough initial draft of the REST improvements that are to go into 2.3:


This is request for feedback and ideas. There is also this top level JIRA issue


Feedback will help flesh out the ideas further and make sure we have a more complete solution

Thoughts appreciated

--
Graeme Rocher
Grails Project Lead
SpringSource




--
Graeme Rocher
Grails Project Lead
SpringSource
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Predrag Knezevic
In reply to this post by Graeme Rocher-2
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

cdeszaq
Create and Edit actions have been in the default scaffolding for quite some time and are essentially just there to give html requests a clear endpoint to request the corresponding (new or edit) form / page from. The goal in continuing to indicate them in the REST specification is to keep them present for allowing easy handling of both html _and_ other content types from the same actions.

In my experience, POSTing to a resource "collection" is the most common way of creating a new resource, getting a response back with the URL of the new resource, whereas PUT is used for updating a specific resource. POSTing leaves URL selection up to the server when creating a new resource, which is far better than relying on the clients, whereas PUT puts more trust / responsibility on the clients. The other issue with using PUT for resource creation is that PUT is idempotent which severely limits what can be done during resource creation, whereas POST is not, leaving things more open / flexible.

- Rick


On Thu, May 2, 2013 at 1:59 PM, Predrag Knežević <[hidden email]> wrote:
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

zyro
In reply to this post by Graeme Rocher-2
hi,

it would be nice to see support for the "pluggable object rendering api"
mentioned in the draft not only for the server side but also for rest
client implementations (parsing/unmarshalling).

for example, i am thinking along the lines of
rest-client-builder -> spring rest template -> json -> jackson support

http://static.springsource.org/spring/docs/3.2.x/spring-framework-reference/html/remoting.html#rest-message-conversion
(MappingJackson2HttpMessageConverter)

zyro

-------- Original Message  --------
Subject: [grails-dev] Initial Draft: Grails 2.3 REST updates
From: Graeme Rocher <[hidden email]>
To: [hidden email] <[hidden email]>
Date: Thu, 2 May 2013 12:20:12 +0200

> Hi all,
>
> I've put together a rough initial draft of the REST improvements that
> are to go into 2.3:
>
> https://github.com/grails/grails-core/wiki/Grails-2.3:-REST-Improvements
>
> This is request for feedback and ideas. There is also this top level
> JIRA issue
>
> http://jira.grails.org/browse/GRAILS-9888
>
> Feedback will help flesh out the ideas further and make sure we have a
> more complete solution
>
> Thoughts appreciated
>
> --
> Graeme Rocher
> Grails Project Lead
> SpringSource

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

aruizca
In reply to this post by cdeszaq
Please add this ticket to the TODO list: "Add support for @RequestMapping Spring MVC annotation in Grails controller class and methods" (http://jira.grails.org/browse/GRAILS-10069) The justification is in the comments.  I think it would fit perfectly to tackle this ticket for Grails 2.3: http://jira.grails.org/browse/GRAILS-9888

There is also a discussion about it here: http://grails.1312388.n4.nabble.com/Can-the-Spring-MVC-RequestMapping-annotation-be-used-in-Grails-2-x-controller-methods-td4644127.html
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Ryan Norris
In reply to this post by cdeszaq
Doesn't this approach violate the "nouns not verbs" idiom?  That is largely considered best practice - introducing the notion of "create" as a semantic verb confuses the notion of what a "resource" is.  Typically if I'm posting to a collection resource, it might look something like:

POST /api/bus/1/passengers

Would add a new passenger to the bus.  Likewise if I want to update a specific passenger on the bus

PUT /api/bus/1/passengers/123

Would update passenger 123 on the bus.  This approach is also aligned with the JAX-RS specification of resources and child resources being exposed through those resources.

I personally think the work on the JAX-RS plugin could be quite foundational to improvements in overall REST support in Grails.  A big win would be to formulate patterns from JAX-RS and apply them to GORM to make GORM RESTful.  


On Thu, May 2, 2013 at 3:17 PM, Rick Jensen <[hidden email]> wrote:
Create and Edit actions have been in the default scaffolding for quite some time and are essentially just there to give html requests a clear endpoint to request the corresponding (new or edit) form / page from. The goal in continuing to indicate them in the REST specification is to keep them present for allowing easy handling of both html _and_ other content types from the same actions.

In my experience, POSTing to a resource "collection" is the most common way of creating a new resource, getting a response back with the URL of the new resource, whereas PUT is used for updating a specific resource. POSTing leaves URL selection up to the server when creating a new resource, which is far better than relying on the clients, whereas PUT puts more trust / responsibility on the clients. The other issue with using PUT for resource creation is that PUT is idempotent which severely limits what can be done during resource creation, whereas POST is not, leaving things more open / flexible.

- Rick


On Thu, May 2, 2013 at 1:59 PM, Predrag Knežević <[hidden email]> wrote:
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email




Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Graeme Rocher-2
"create" only exists for the browser to also function with RESTful styles. 


On Fri, May 3, 2013 at 3:35 PM, Ryan Norris <[hidden email]> wrote:
Doesn't this approach violate the "nouns not verbs" idiom?  That is largely considered best practice - introducing the notion of "create" as a semantic verb confuses the notion of what a "resource" is.  Typically if I'm posting to a collection resource, it might look something like:

POST /api/bus/1/passengers

Would add a new passenger to the bus.  Likewise if I want to update a specific passenger on the bus

PUT /api/bus/1/passengers/123

Would update passenger 123 on the bus.  This approach is also aligned with the JAX-RS specification of resources and child resources being exposed through those resources.

I personally think the work on the JAX-RS plugin could be quite foundational to improvements in overall REST support in Grails.  A big win would be to formulate patterns from JAX-RS and apply them to GORM to make GORM RESTful.  



On Thu, May 2, 2013 at 3:17 PM, Rick Jensen <[hidden email]> wrote:
Create and Edit actions have been in the default scaffolding for quite some time and are essentially just there to give html requests a clear endpoint to request the corresponding (new or edit) form / page from. The goal in continuing to indicate them in the REST specification is to keep them present for allowing easy handling of both html _and_ other content types from the same actions.

In my experience, POSTing to a resource "collection" is the most common way of creating a new resource, getting a response back with the URL of the new resource, whereas PUT is used for updating a specific resource. POSTing leaves URL selection up to the server when creating a new resource, which is far better than relying on the clients, whereas PUT puts more trust / responsibility on the clients. The other issue with using PUT for resource creation is that PUT is idempotent which severely limits what can be done during resource creation, whereas POST is not, leaving things more open / flexible.

- Rick


On Thu, May 2, 2013 at 1:59 PM, Predrag Knežević <[hidden email]> wrote:
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email







--
Graeme Rocher
Grails Project Lead
SpringSource
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

cdeszaq
@RyanNorris, what Graeme said is the critical piece: Allow existing html endpoints work to also serve non-html resource representations. Rather than have a separate "namespace" in the URL for API calls, the idea is that you can use your existing endpoints. _Not_ having "/api" in your URLs is cleaner, and requires less code, than just using your html URLs. Nothing, of course, would preclude you from still putting "/api" in the URL, however, if you so choose.


On Fri, May 3, 2013 at 9:04 AM, Graeme Rocher <[hidden email]> wrote:
"create" only exists for the browser to also function with RESTful styles. 


On Fri, May 3, 2013 at 3:35 PM, Ryan Norris <[hidden email]> wrote:
Doesn't this approach violate the "nouns not verbs" idiom?  That is largely considered best practice - introducing the notion of "create" as a semantic verb confuses the notion of what a "resource" is.  Typically if I'm posting to a collection resource, it might look something like:

POST /api/bus/1/passengers

Would add a new passenger to the bus.  Likewise if I want to update a specific passenger on the bus

PUT /api/bus/1/passengers/123

Would update passenger 123 on the bus.  This approach is also aligned with the JAX-RS specification of resources and child resources being exposed through those resources.

I personally think the work on the JAX-RS plugin could be quite foundational to improvements in overall REST support in Grails.  A big win would be to formulate patterns from JAX-RS and apply them to GORM to make GORM RESTful.  



On Thu, May 2, 2013 at 3:17 PM, Rick Jensen <[hidden email]> wrote:
Create and Edit actions have been in the default scaffolding for quite some time and are essentially just there to give html requests a clear endpoint to request the corresponding (new or edit) form / page from. The goal in continuing to indicate them in the REST specification is to keep them present for allowing easy handling of both html _and_ other content types from the same actions.

In my experience, POSTing to a resource "collection" is the most common way of creating a new resource, getting a response back with the URL of the new resource, whereas PUT is used for updating a specific resource. POSTing leaves URL selection up to the server when creating a new resource, which is far better than relying on the clients, whereas PUT puts more trust / responsibility on the clients. The other issue with using PUT for resource creation is that PUT is idempotent which severely limits what can be done during resource creation, whereas POST is not, leaving things more open / flexible.

- Rick


On Thu, May 2, 2013 at 1:59 PM, Predrag Knežević <[hidden email]> wrote:
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email







--
Graeme Rocher
Grails Project Lead
SpringSource

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Daniel Woods
It seems like it would be a good precedence to have a deterministic way to decide whether to use PUT or PATCH verbs when updating. The PUT spec says that the whole document needs to be replaced, while PATCH can allow for incremental updates and we can garner some benefits from that (network overhead, for example). Using the PATCH method could be mixed in with strategies like Hibernate's dynamic updates to further improve performance.

Plus, I think that using PATCH for updating is an idea that's already gained traction in the REST API world.

dan


On Fri, May 3, 2013 at 10:30 AM, Rick Jensen <[hidden email]> wrote:
@RyanNorris, what Graeme said is the critical piece: Allow existing html endpoints work to also serve non-html resource representations. Rather than have a separate "namespace" in the URL for API calls, the idea is that you can use your existing endpoints. _Not_ having "/api" in your URLs is cleaner, and requires less code, than just using your html URLs. Nothing, of course, would preclude you from still putting "/api" in the URL, however, if you so choose.


On Fri, May 3, 2013 at 9:04 AM, Graeme Rocher <[hidden email]> wrote:
"create" only exists for the browser to also function with RESTful styles. 


On Fri, May 3, 2013 at 3:35 PM, Ryan Norris <[hidden email]> wrote:
Doesn't this approach violate the "nouns not verbs" idiom?  That is largely considered best practice - introducing the notion of "create" as a semantic verb confuses the notion of what a "resource" is.  Typically if I'm posting to a collection resource, it might look something like:

POST /api/bus/1/passengers

Would add a new passenger to the bus.  Likewise if I want to update a specific passenger on the bus

PUT /api/bus/1/passengers/123

Would update passenger 123 on the bus.  This approach is also aligned with the JAX-RS specification of resources and child resources being exposed through those resources.

I personally think the work on the JAX-RS plugin could be quite foundational to improvements in overall REST support in Grails.  A big win would be to formulate patterns from JAX-RS and apply them to GORM to make GORM RESTful.  



On Thu, May 2, 2013 at 3:17 PM, Rick Jensen <[hidden email]> wrote:
Create and Edit actions have been in the default scaffolding for quite some time and are essentially just there to give html requests a clear endpoint to request the corresponding (new or edit) form / page from. The goal in continuing to indicate them in the REST specification is to keep them present for allowing easy handling of both html _and_ other content types from the same actions.

In my experience, POSTing to a resource "collection" is the most common way of creating a new resource, getting a response back with the URL of the new resource, whereas PUT is used for updating a specific resource. POSTing leaves URL selection up to the server when creating a new resource, which is far better than relying on the clients, whereas PUT puts more trust / responsibility on the clients. The other issue with using PUT for resource creation is that PUT is idempotent which severely limits what can be done during resource creation, whereas POST is not, leaving things more open / flexible.

- Rick


On Thu, May 2, 2013 at 1:59 PM, Predrag Knežević <[hidden email]> wrote:
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email







--
Graeme Rocher
Grails Project Lead
SpringSource


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Ryan Norris
In reply to this post by cdeszaq
The api prefixes in my examples were inconsequential.  My point was more around a concern around the "create" as something representative of a resource and mingling verbs with nouns.  So, amending my example to make sure that I'm lucid on my point:

POST /bus/1/passengers HTTP/1.1
Content-type: application/json
Accepts: application/json

As opposed to

POST /bus/1/passengers/create HTTP/1.1
Content-type: application/json
Accepts: application/json

@Graeme - can you elaborate on what you mean?  Why isn't the above as applicable without the idiomatic confusion?


On Fri, May 3, 2013 at 10:30 AM, Rick Jensen <[hidden email]> wrote:
@RyanNorris, what Graeme said is the critical piece: Allow existing html endpoints work to also serve non-html resource representations. Rather than have a separate "namespace" in the URL for API calls, the idea is that you can use your existing endpoints. _Not_ having "/api" in your URLs is cleaner, and requires less code, than just using your html URLs. Nothing, of course, would preclude you from still putting "/api" in the URL, however, if you so choose.


On Fri, May 3, 2013 at 9:04 AM, Graeme Rocher <[hidden email]> wrote:
"create" only exists for the browser to also function with RESTful styles. 


On Fri, May 3, 2013 at 3:35 PM, Ryan Norris <[hidden email]> wrote:
Doesn't this approach violate the "nouns not verbs" idiom?  That is largely considered best practice - introducing the notion of "create" as a semantic verb confuses the notion of what a "resource" is.  Typically if I'm posting to a collection resource, it might look something like:

POST /api/bus/1/passengers

Would add a new passenger to the bus.  Likewise if I want to update a specific passenger on the bus

PUT /api/bus/1/passengers/123

Would update passenger 123 on the bus.  This approach is also aligned with the JAX-RS specification of resources and child resources being exposed through those resources.

I personally think the work on the JAX-RS plugin could be quite foundational to improvements in overall REST support in Grails.  A big win would be to formulate patterns from JAX-RS and apply them to GORM to make GORM RESTful.  



On Thu, May 2, 2013 at 3:17 PM, Rick Jensen <[hidden email]> wrote:
Create and Edit actions have been in the default scaffolding for quite some time and are essentially just there to give html requests a clear endpoint to request the corresponding (new or edit) form / page from. The goal in continuing to indicate them in the REST specification is to keep them present for allowing easy handling of both html _and_ other content types from the same actions.

In my experience, POSTing to a resource "collection" is the most common way of creating a new resource, getting a response back with the URL of the new resource, whereas PUT is used for updating a specific resource. POSTing leaves URL selection up to the server when creating a new resource, which is far better than relying on the clients, whereas PUT puts more trust / responsibility on the clients. The other issue with using PUT for resource creation is that PUT is idempotent which severely limits what can be done during resource creation, whereas POST is not, leaving things more open / flexible.

- Rick


On Thu, May 2, 2013 at 1:59 PM, Predrag Knežević <[hidden email]> wrote:
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email







--
Graeme Rocher
Grails Project Lead
SpringSource


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

cdeszaq
In reply to this post by Daniel Woods
I think the idea of being _able_ to use PATCH is great, but I think that could easily be left out of v2.3, and added in with a later update. I would _hate_ to see v2.3 delayed due to the complexities of adding PATCH to the Update flow.

From the (admittedly limited) information I have about PATCH, it's still relatively rare as far as implementations that support it as an HTTP method. I think it would be, possibly, great to be able to specify that an update uses PUT or PATCH, and also have the ability for PATCH to be specified and have the update fall back to PUT if the server complains.

- Rick


On Fri, May 3, 2013 at 11:30 AM, Daniel Woods <[hidden email]> wrote:
It seems like it would be a good precedence to have a deterministic way to decide whether to use PUT or PATCH verbs when updating. The PUT spec says that the whole document needs to be replaced, while PATCH can allow for incremental updates and we can garner some benefits from that (network overhead, for example). Using the PATCH method could be mixed in with strategies like Hibernate's dynamic updates to further improve performance.

Plus, I think that using PATCH for updating is an idea that's already gained traction in the REST API world.

dan


On Fri, May 3, 2013 at 10:30 AM, Rick Jensen <[hidden email]> wrote:
@RyanNorris, what Graeme said is the critical piece: Allow existing html endpoints work to also serve non-html resource representations. Rather than have a separate "namespace" in the URL for API calls, the idea is that you can use your existing endpoints. _Not_ having "/api" in your URLs is cleaner, and requires less code, than just using your html URLs. Nothing, of course, would preclude you from still putting "/api" in the URL, however, if you so choose.


On Fri, May 3, 2013 at 9:04 AM, Graeme Rocher <[hidden email]> wrote:
"create" only exists for the browser to also function with RESTful styles. 


On Fri, May 3, 2013 at 3:35 PM, Ryan Norris <[hidden email]> wrote:
Doesn't this approach violate the "nouns not verbs" idiom?  That is largely considered best practice - introducing the notion of "create" as a semantic verb confuses the notion of what a "resource" is.  Typically if I'm posting to a collection resource, it might look something like:

POST /api/bus/1/passengers

Would add a new passenger to the bus.  Likewise if I want to update a specific passenger on the bus

PUT /api/bus/1/passengers/123

Would update passenger 123 on the bus.  This approach is also aligned with the JAX-RS specification of resources and child resources being exposed through those resources.

I personally think the work on the JAX-RS plugin could be quite foundational to improvements in overall REST support in Grails.  A big win would be to formulate patterns from JAX-RS and apply them to GORM to make GORM RESTful.  



On Thu, May 2, 2013 at 3:17 PM, Rick Jensen <[hidden email]> wrote:
Create and Edit actions have been in the default scaffolding for quite some time and are essentially just there to give html requests a clear endpoint to request the corresponding (new or edit) form / page from. The goal in continuing to indicate them in the REST specification is to keep them present for allowing easy handling of both html _and_ other content types from the same actions.

In my experience, POSTing to a resource "collection" is the most common way of creating a new resource, getting a response back with the URL of the new resource, whereas PUT is used for updating a specific resource. POSTing leaves URL selection up to the server when creating a new resource, which is far better than relying on the clients, whereas PUT puts more trust / responsibility on the clients. The other issue with using PUT for resource creation is that PUT is idempotent which severely limits what can be done during resource creation, whereas POST is not, leaving things more open / flexible.

- Rick


On Thu, May 2, 2013 at 1:59 PM, Predrag Knežević <[hidden email]> wrote:
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email







--
Graeme Rocher
Grails Project Lead
SpringSource



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Eamonn O'Connell-2
Is index or list the defacto action to display a list of the respective resource? Going on the spec here, it seems to be index. 


On 3 May 2013 19:19, Rick Jensen <[hidden email]> wrote:
I think the idea of being _able_ to use PATCH is great, but I think that could easily be left out of v2.3, and added in with a later update. I would _hate_ to see v2.3 delayed due to the complexities of adding PATCH to the Update flow.

From the (admittedly limited) information I have about PATCH, it's still relatively rare as far as implementations that support it as an HTTP method. I think it would be, possibly, great to be able to specify that an update uses PUT or PATCH, and also have the ability for PATCH to be specified and have the update fall back to PUT if the server complains.

- Rick


On Fri, May 3, 2013 at 11:30 AM, Daniel Woods <[hidden email]> wrote:
It seems like it would be a good precedence to have a deterministic way to decide whether to use PUT or PATCH verbs when updating. The PUT spec says that the whole document needs to be replaced, while PATCH can allow for incremental updates and we can garner some benefits from that (network overhead, for example). Using the PATCH method could be mixed in with strategies like Hibernate's dynamic updates to further improve performance.

Plus, I think that using PATCH for updating is an idea that's already gained traction in the REST API world.

dan


On Fri, May 3, 2013 at 10:30 AM, Rick Jensen <[hidden email]> wrote:
@RyanNorris, what Graeme said is the critical piece: Allow existing html endpoints work to also serve non-html resource representations. Rather than have a separate "namespace" in the URL for API calls, the idea is that you can use your existing endpoints. _Not_ having "/api" in your URLs is cleaner, and requires less code, than just using your html URLs. Nothing, of course, would preclude you from still putting "/api" in the URL, however, if you so choose.


On Fri, May 3, 2013 at 9:04 AM, Graeme Rocher <[hidden email]> wrote:
"create" only exists for the browser to also function with RESTful styles. 


On Fri, May 3, 2013 at 3:35 PM, Ryan Norris <[hidden email]> wrote:
Doesn't this approach violate the "nouns not verbs" idiom?  That is largely considered best practice - introducing the notion of "create" as a semantic verb confuses the notion of what a "resource" is.  Typically if I'm posting to a collection resource, it might look something like:

POST /api/bus/1/passengers

Would add a new passenger to the bus.  Likewise if I want to update a specific passenger on the bus

PUT /api/bus/1/passengers/123

Would update passenger 123 on the bus.  This approach is also aligned with the JAX-RS specification of resources and child resources being exposed through those resources.

I personally think the work on the JAX-RS plugin could be quite foundational to improvements in overall REST support in Grails.  A big win would be to formulate patterns from JAX-RS and apply them to GORM to make GORM RESTful.  



On Thu, May 2, 2013 at 3:17 PM, Rick Jensen <[hidden email]> wrote:
Create and Edit actions have been in the default scaffolding for quite some time and are essentially just there to give html requests a clear endpoint to request the corresponding (new or edit) form / page from. The goal in continuing to indicate them in the REST specification is to keep them present for allowing easy handling of both html _and_ other content types from the same actions.

In my experience, POSTing to a resource "collection" is the most common way of creating a new resource, getting a response back with the URL of the new resource, whereas PUT is used for updating a specific resource. POSTing leaves URL selection up to the server when creating a new resource, which is far better than relying on the clients, whereas PUT puts more trust / responsibility on the clients. The other issue with using PUT for resource creation is that PUT is idempotent which severely limits what can be done during resource creation, whereas POST is not, leaving things more open / flexible.

- Rick


On Thu, May 2, 2013 at 1:59 PM, Predrag Knežević <[hidden email]> wrote:
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email







--
Graeme Rocher
Grails Project Lead
SpringSource




Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Javier Muniz
In reply to this post by Ryan Norris
I understood create and edit to be the URIs for the create and edit UI (accessed via GET) whereas actually creating a resource would be done with the POST to /passengers

This would match what another similarly named framework does for resource routes :)

On May 3, 2013, at 10:21 AM, "Ryan Norris" <[hidden email]> wrote:

The api prefixes in my examples were inconsequential.  My point was more around a concern around the "create" as something representative of a resource and mingling verbs with nouns.  So, amending my example to make sure that I'm lucid on my point:

POST /bus/1/passengers HTTP/1.1
Content-type: application/json
Accepts: application/json

As opposed to

POST /bus/1/passengers/create HTTP/1.1
Content-type: application/json
Accepts: application/json

@Graeme - can you elaborate on what you mean?  Why isn't the above as applicable without the idiomatic confusion?


On Fri, May 3, 2013 at 10:30 AM, Rick Jensen <[hidden email]> wrote:
@RyanNorris, what Graeme said is the critical piece: Allow existing html endpoints work to also serve non-html resource representations. Rather than have a separate "namespace" in the URL for API calls, the idea is that you can use your existing endpoints. _Not_ having "/api" in your URLs is cleaner, and requires less code, than just using your html URLs. Nothing, of course, would preclude you from still putting "/api" in the URL, however, if you so choose.


On Fri, May 3, 2013 at 9:04 AM, Graeme Rocher <[hidden email]> wrote:
"create" only exists for the browser to also function with RESTful styles. 


On Fri, May 3, 2013 at 3:35 PM, Ryan Norris <[hidden email]> wrote:
Doesn't this approach violate the "nouns not verbs" idiom?  That is largely considered best practice - introducing the notion of "create" as a semantic verb confuses the notion of what a "resource" is.  Typically if I'm posting to a collection resource, it might look something like:

POST /api/bus/1/passengers

Would add a new passenger to the bus.  Likewise if I want to update a specific passenger on the bus

PUT /api/bus/1/passengers/123

Would update passenger 123 on the bus.  This approach is also aligned with the JAX-RS specification of resources and child resources being exposed through those resources.

I personally think the work on the JAX-RS plugin could be quite foundational to improvements in overall REST support in Grails.  A big win would be to formulate patterns from JAX-RS and apply them to GORM to make GORM RESTful.  



On Thu, May 2, 2013 at 3:17 PM, Rick Jensen <[hidden email]> wrote:
Create and Edit actions have been in the default scaffolding for quite some time and are essentially just there to give html requests a clear endpoint to request the corresponding (new or edit) form / page from. The goal in continuing to indicate them in the REST specification is to keep them present for allowing easy handling of both html _and_ other content types from the same actions.

In my experience, POSTing to a resource "collection" is the most common way of creating a new resource, getting a response back with the URL of the new resource, whereas PUT is used for updating a specific resource. POSTing leaves URL selection up to the server when creating a new resource, which is far better than relying on the clients, whereas PUT puts more trust / responsibility on the clients. The other issue with using PUT for resource creation is that PUT is idempotent which severely limits what can be done during resource creation, whereas POST is not, leaving things more open / flexible.

- Rick


On Thu, May 2, 2013 at 1:59 PM, Predrag Knežević <[hidden email]> wrote:
> Feedback will help flesh out the ideas further and make sure we have a more
> complete solution

  I am the author of grails marshallers
http://grails.org/plugin/marshallers plugin. Perhaps some of the code
could re-used in this context? If you need any help in that direction,
let me know.

  BTW, what is the motivation for introducing create and edit actions
(and using HTTP GET for that)?  REST services I have seen/used up to
now go in the following direction:

* GET /book/$id - read resource with given id
* PUT /book - create the resource or replace it if existed
* DELETE /book - remove the resource

  Best,

Predrag

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email







--
Graeme Rocher
Grails Project Lead
SpringSource


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

Marc Palmer Local
In reply to this post by cdeszaq
Hi all,

I thought I'd give some input on this... having in the last year designed and implemented multiple revisions of the live REST API for a production iOS client/server service for my customer.

1. REST CLIENT

I am confused by the REST client stuff.

As I understand it this is intended to make it easy to consume another REST service, by mapping it to domains.

The problem for me here is that I don't know what APIs one would be consuming like this. Without support for proprietary variants of OAuth and non-OAuth authentication schemes (these do exist), and support for the various API versioning mechanisms out there (see e.g. App.Net's migrations mechanism), I can't see how this is useful except for internally create APIs.

If this is indeed the case and/or intention, I think this needs to be made clear. As the discussions on this thread have shown, there is no one way to cut REST even at the HTTP method level, let alone the URI endpoints, so I am concerned that this will just create another "its not really useful beyond demos" feature.

2. REST SERVER actions

On the server REST proposals, a GET for "create" makes no sense to me at all. I've never seen a REST API implement create in this way. Ditto GET /edit for "edit" action.

I think those should be totally cut form the standard behaviour, I'm happy to be proven wrong but it would seem to me that those fall very much outside the "80% case".

3. REST SERVER payload formats

It makes no sense to specify per controller what response formats there are. This is a protocol level specification detail. This simply means you have to duplicate this same - usually invariant - info across all the controllers.

3. REST SERVER versioning

I see no support for API versioning. Without this the feature will be a toy.

Versioning is not as simple as having multiple URL mappings. Applications typically need to support multiple API versions concurrently, and the only sane way to do this is for your service code (and perhaps controllers) to be able to easily tell which version of the API was requested. This requires filtering this out of the URL and making it easily available.

Regarding the previous point, the request and response formats can vary per API version. Another reason why they shouldn't be in controllers.

Versioning is also painful when it comes to writing tests - you have to maintain the old tests and the new ones, for all the versions of the API the application concurrently supports, as well as maintaining the old URL mappings, and doing alternative marshalling and validation based on the current API version, given that a lot of the could will remain - and should remain - shared.

4. REST SERVER viability

All in all, I personally don't think this kind of REST support is going to be useful except for naïve applications.

Often with REST APIs you are dealing with thousands of installed clients - be they mobile applications or remote web services - which you cannot force to upgrade. This is a critical consideration.

Any mechanism that does not support the developer completely in achieving this is leading them down a painful path.

I personally think that new REST client/server stuff does not warrant any place in core grails at all, let alone as a default plugin.

This should be implemented as a REST API plugin that lets you define versioned API protocol artefacts instead of URL mappings, and this would generate all the URL mappings and endpoints etc for you according to the specification you provide.

This feels like a much more modern and effective concept to me. Versioned APIs are really much like migrations. The system as described feels too my like the old way of doing things (like scaffolding all over again - which is still enduring pain achieving deep usefulness years later)

We have to guide people to sane API designs. Groovy is great at DSLs. Grails has a good artefact system. Let's use them.

We need a task-oriented solution that is not stuck in the existing 5 year+ old mindset.

When you are creating an API you:

1) Must design it, this means creating or generating some kind of spec document
2) Must decide the formats supported
3) Must decide how you map different versions into the URI space
4) Must decide how your endpoints are implemented, and this can vary
5) Decide how you implement authentication
6) Deal with the occasional exception such as multipart POST for data uploads, or actions that return some HTML fragment (a document)
7) Think about marshalled responses that contain different data depending on context such as user's permissions
8) Must have an easy way to test it, across multiple API versions in the same test run

e.g. grails-app/apis/Main_1_0.groovy:

def specification = {
        version 1.0
        formats 'xml', 'json' // req+response implied to support same, asymmetry in sane APIs is rare
        baseEndpoint = '/api/$version'

        endpoints {
                book domain:'Book'

                author domain:'Author'

                publisher() // defaults to PublisherApiController by convention

                category controller:'categoryAdminApi'

                users domain:'User', allowedVerbs:['get', 'list']
        }
}

An application or plugin can provide these artefacts and multiple will exist concurrently.

This allows for safety checking that is problematic with UrlMappings where there is no safety in the way that plugins expose URL mappings that clash with other plugins or the application.

This system could output clear errors at startup or compile time of the form:

Plugins [something] and [otherone] are both attempting to expose an API at base '/api/1.0'
Plugins [something] and [otherone] are both attempting to expose an API at base '/api/1.0' with endpoint "publisher"

This kind of thing, with specification endpoint merging supported, allows modular applications where in-house plugins add functionality to APIs defined elsewhere, something that I know at least a few existing Grails applications would like to make use of I'm sure. I see more and more componentized Grails apps now where bespoke deployments are made per-customer with various features.

It also allows plugins to expose entire "mini APIs" of their own.

Anyway, there's my thoughts on it. I'm hoping for something more revolutionary and more useful in real apps. I can't see any of my customers having any use for the 2.3 REST features as proposed I'm afraid. I'm not being mean - its just the honest truth.

Thanks
Marc
~ ~ ~
Marc Palmer
Freelancer (iOS/Grails/Groovy/Java/UX)

Blog: http://transition.io & http://grailsrocks.com
Résumé: http://marcpalmer.net
Twitter: http://twitter.com/wangjammer5
App.Net: https://alpha.app.net/marcpalmer 










---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Initial Draft: Grails 2.3 REST updates

bmcguire
In reply to this post by Graeme Rocher-2
First off thank you for spending the time to make this a first class feature in Grails, it is a very welcome improvement.

Looking at the mappings below I don't see a reason for the url mappings GET /book/edit or GET /book/create, they seem as though they would be the same thing as the GET /book action. I have built out REST clients and have never needed different GET commands for create and edit. That said they aren't harming anyone one if you don't need to implement them, but to me it does add a level of confusion. The same thing applies to the 'resources' mapping.

"/book"(resource:'book')

Will create URL mappings like:

URLGrails Action
GET /book/createcreate
POST /booksave
GET /bookshow
GET /book/editedit
PUT /bookupdate
DELETE /bookdelete


Ben McGuire

________________________________
From: Graeme Rocher <[hidden email]>
To: "[hidden email]" <[hidden email]>
Sent: Thursday, May 2, 2013 3:20 AM
Subject: [grails-dev] Initial Draft: Grails 2.3 REST updates



Hi all,

I've put together a rough initial draft of the REST improvements that are to go into 2.3:

https://github.com/grails/grails-core/wiki/Grails-2.3:-REST-Improvements

This is request for feedback and ideas. There is also this top level JIRA issue

http://jira.grails.org/browse/GRAILS-9888

Feedback will help flesh out the ideas further and make sure we have a more complete solution

Thoughts appreciated

--

Graeme Rocher
Grails Project Lead
SpringSource

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


12
Loading...