Grails Controllers and REST, part 3

In the previous part of this series, I talked about using POST, PUT, and DELETE to insert, update, and delete Cows into our app. In this part, we'll actually figure out if this thing works. We can do manual testing from the command line via curl, and we can also do automated testing using the Grails functional-test plugin.

Grails Controllers and REST, part 2

In part one of this series, I looked at doing REST-ful GET commands for lists and elements by embedding the code in the same functions used for HTML.  That was the easy part - expressing data as XML or JSON and rendering "Not Found" messages.  In this part, we will look at the REST-ful ways to modify the system, through PUT, POST, and DELETE.

Let's start with a review of the HTTP verbs and how they relate to REST:

GET

This one is pretty simple: GET is a read request, and returns the resource specified by the URI.

DELETE

DELETE will remove the resource from the server.  'Nuff said.

PUT

PUT is more or less equivalent to an UPDATE, or an INSERT in some cases.  By strict interpretation, PUT requires that the resource be modified as a whole, and calls are considered idempotent, which means, repeating the same call over and over will have the same effect.  This is important- if a system generates identifiers which are part of the resource, then PUT should probably not be used as an INSERT.  After all, repeated calls that do not contain the identifier would need to be reconciled with previous calls in order to avoid multiple inserts.

POST

"The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line." (w3c)  Ummm, what?  In layman's terms, a POST can be used to modify a portion of a resource (like adding elements to a list), or to submit a block of data (like the contents of a form).  Because its definition is so generic, it can be used for RPC-style function calls as well.

(Sidebar: before you go emailing me that you don't agree with the POST vs PUT interpretation, this is *my* interpretation of the spec.  There are many bright people who agree, and many bright people who disagree.  Too bad the w3c didn't write the spec more definitively...)

Now, on to the code.

Grails Controllers and REST, part 1

There are plenty of how-to's describing the conventions used by Grails Controllers, so I'm not going into that again.  As I mentioned earlier, Grails Controllers can be a lot more useful than just displaying web pages.  With a little bit of extra plumbing, that same controller that is providing CRUD to HTML pages can be generating JSON or XML to a caller as well.

REST uses the verbs built right into HTTP as the way to define an action to take upon the destination resource, as denoted in the URI.  The Grails conventions fit very nicely into the way humans think of REST, and with a combination of UrlMappings and the "withFormat" command, you can easily extend a Grails Controller to accommodate non-HTML formats.  We'll get into it after the jump.