REST - Taking a Closer Look (Part 5)

In this post, we'll take a closer look at the update process using PUT with the Grails project.   REST defines updates as a HTTP PUT method.

First we need to make a few adjustments to the code to make the update operation respond to the PUT method and alter the edit form to ensure it is sending in a method of PUT.

Alter the allowedMethods array to recognize PUT for the update method.

Alter the form method to ensure it sends PUT as the method.

Now that we have ensured the method is set to PUT on the form and the controller will accept PUT as the method from the client let's test.  (After selecting a specific book, click the Edit button along the bottom of the view.)  Altering some data and clicking the Update button we should be in business to see the transaction.  The following screenshot details the HTTP headers transferred during the state transition.

Here we can see that the request was actually done using POST.  Internally within the request parameters a PUT method is specified.  This is detailed further in the Grails 2.0.0 documentation.

Issuing a request with a method other than GET or POST from a regular browser is not possible without some help from Grails.

This doesn't seem to be consistent with the REST architecture or the HTTP v1.1 specification.  Grails is also blocking a method of PUT coming from the browser with a 405 - Method Not Allowed response.  Requests made with cUrl go through without error.

$ curl --request PUT http://localhost:8080/research-grails-rest/book/update/1 --verbose
* About to connect() to localhost port 8080 (#0)
*   Trying ::1... connected
* Connected to localhost (::1) port 8080 (#0)
> PUT /research-grails-rest/book/update/1 HTTP/1.1
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
> Host: localhost:8080
> Accept: */*
>
< HTTP/1.1 302 Moved Temporarily
< Server: Apache-Coyote/1.1
< Set-Cookie: JSESSIONID=F91DEA3433A1F745B249C0F7E3E9988E; Path=/research-grails-rest/; HttpOnly
< Location: http://localhost:8080/research-grails-rest/book/show/1
< Content-Length: 0
< Date: Tue, 24 Jan 2012 10:45:05 GMT
<
* Connection #0 to host localhost left intact
* Closing connection #0

The response location,  http://localhost:8080/research-grails-rest/book/show/1, indicates the controller received the request correctly and performed the update.

What am I trying to get at?  One concern I have is support by most/all browsers for the HTTP v1.1 specification.  Another concern is around the heavy handiness around the method support on Grails part.  I concede I am now Grails expert and there may be a very simple solution to this.  I haven't found it yet if there is.  Furthermore, quick check of delete operation from the browser blocks the DELTE method even after altering the allowedMethods.

So what have we learned?  The PUT and DELETE methods have special considerations when involving the Grails built views.  It may be worth approaching another framework to interact with the REST services provided.  However, the controller has tightly integrated the responses on each call with the next view.  I think this is intended due to the nature of Grails application development.

REST - Taking a Closer Look (Part 4)

In the previous posts, we've discussed the general project, defined the concept of REST and taken a look at the list, show and save operations.  Now, let's talk a little shop and dissect the concept of REST a bit further.

REST has some very important design concepts that need to be leveraged to be successful.  First, a rich and easy interface.  This is important for two reasons.  Building a client implementation around a set of REST services can focus on user experience and ignore the data needs.  That is to say, the data is well-defined and the developer building the client can rely on those services to provide specific data.  The application will be built around that data without intermixing the client specific code.

The second important reason is, a developer can build any client around a set of REST services.  Why?  The data has no complicating details blurring the line between the user experience and the data.  In doing so, it makes it more adaptable to move from a purely web-based client to say a mobile web client.  Later, moving to a native client or game console becomes a reality.  Later on down the road, the REST API is published and developers are developing custom applications, much like Twitter, Amazon and others.

Another idea I have read about but do not fully understand is the concept of idempotent resources.  Idempotent is defined as an element multiplied by itself remains unchanged.  The simplest case I can come up with is 1.  1 multiplied by 1 is still 1.

So how does this apply to resource in your system?  Making a request to the same URI should result in the same operation time and time again.  In other words, creating an entry for a book with the same title should result in the same book being created or denied every time.  Only one book is created with that title.  Both PUT and DELETE methods are idempotent.  The GET method is also idempotent given that there are no lasting changes on the resource being requested.  POST is an update operation and can result in attributes of a given resource being altered.  It does not qualify as an idempotent method.

Now, we have defined why REST has good qualities. It provides a rich and easy interface to resources or decouples the client from the data, in doing so, making the data and services scalable.  We have cleared up the concept of idempotent and what that means to a resource in our system.

It is important to remember that REST isn't a specification like SOAP.  It is merely a suggestion of an architectural design around how to serve data.  There are goals within the design to decouple data from the client so that these services are scalable, reliable and well-defined for future client implementations.

REST - Taking a Closer Look (Part 3)

In the previous posts, we've discussed the general project, defined the concept of REST and taken a look at how the list or read operation.  Now as promised in REST - Taking a Closer Look (Part 2) we'll look at the POST method or create operation.

After clicking the 'Create Book' button, a form for the attributes about the book is displayed.  After entering the required values, we can click the 'Create' button.

Create Book Form

After clicking the 'Create' button the new book properties will be sent to the server and stored in the database.  The following screenshot details the request/response transaction from the browser with the client.  

Save Book Transition

The important pieces to note are:

• Request URI is http://localhost:8080/research-grails-rest/book/save.
• Request method is POST.
• Response status code is 302.
• Response location is http://localhost:8080/research-grails-rest/book/show/1.

The rest of the request and response headers are standard protocol speak.  The ones identified above indicate exactly how the data was saved and how the following response to the show state.

We have now seen three URIs in the transition between book listing, saving and showing a book.  The list operation is done with the GET method and the URI was formed as, http://localhost:8080/research-grails-rest/book/list.  The save operation is done using the POST method and the URI was, http://localhost:8080/research-grails/rest/book/save.  Lastly, the show operation also used a GET method, however specified an id to identify one of the items in the collection like so, http://localhost:8080/research-grails-rest/show/1.  

What we have seen so far is the basic blocks to working with a single resource.  Later we'll dig in further to understand the request model for updating, deleting and multiple items in the collection.  Next we'll take a closer look at REST and put a little more definition around what it is.

REST - Taking a Closer Look (Part 2)

First goal is understanding the request model as stated in my previous post REST - Taking a Closer Look (Part 1).  For this portion of the exercise, I will start take a closer look at the Book implementation.

The book model is simple concept and one that we would recognize from our daily lives.  A book has basic properties,

• title
• description
• author
• ISBN

What is REST?  REST is representational state transfer (see Wikipedia for more details).  More or less, it's a software architecture by which we transfer state from one place to another.  In terms of the web, transferring state of resources from the client (browser) to the server (web server->database).  I strongly suggest reading the Wikipedia entry, as it has some very useful and important details on implementation and separation of concerns.

REST sets out to model the concept of CRUD operations (Create, Read, Update, Delete).  It mimics these operations by using POST to Create, GET to Read, PUT to Update, DELETE to, well, Delete. 

With a simple understanding of REST, let's look a little closer at a Book implementation.  Initially, you'll want to see a list of books that are available.  We would model a URL using the guidance of REST like this.

GET http://localhost:8080/research-grails-rest/book/list

This URL has no unique pieces to it.  The resource is defined by book and the operation is defined by list. As a result, all defined knowledge of the representation of a book will be listed.  We can say this about any resource that is available in the system that provides an authorized list operation.  Within the context of the Grails application, all of the work is done on the server and returned in an HTML page.  However, in an Ajax based client, the list operation would return all of the data as a data structure and decouple the operation from the client view.

Screenshot: Result of book/list.

As a part of the architecture, the GET request could be marked as cacheable.  In other words, the browser could use a copy of this data from it's local cache rather than making a request to the server.  The resource, book, would have to mark the list operation as cacheable and provide a timeframe in which that cached data is considered fresh.  Once that cache entry is considered stale by the browser or by revalidation by the server, a new version of the resource will be made available to the end user.

For a simple operation like, GET, this about the extent of it.  In the next post, I will discuss the POST method (Create).

REST - Taking a Closer Look (Part 1)

One of the challenges that I have found in regards to REST is really understanding how it used in practice.  Looking across the internet, there appears to be a vast amount of documentation that talks about the basics.  I have two goals for gathering a better understanding of REST.  First, understand the request model which is well documented all over the internet.  The best way learn something is by doing.  Secondly, look at how more complex operations are constructed and how they impact the design of application.

To frame this out, I am working with Grails and building on top of the implementation discussed in the screencast, Jump Into Grails 2.0.  My experience with Groovy is limited, but I have a good background in Java which I am hoping to leverage in learning/understanding Groovy.  The screencast takes an approach of building a basic application in Grails encompassing the following,

• Setting up application configuration and plugins
• Building basic model, view and controller implementations of 
• User
• Role
• User Role mapping
• Discuss Unit testing - in my opinion very handy and largely automated
• Building a new model, view and controller of a Book.

I don't intend to reproduce the screencast here.  However, as part of this first part I would like to make sure there is enough understanding about the Grails project and how it is built for those looking to understand and answer the same questions I am setting out to answer.

For complete source, access the git repository through git : git://github.com/mhorner/research-grails-rest.git or view it at https://github.com/mhorner/research-grails-rest.

Texas Tornado Brown Ale

The Texas Tornado brown ale is a beer I first brewed last year around this time.  It's a hop forward beer with a Cascade hops that we all love an enjoy through our summertime pale ales.  This recipe is taken directly from the Ray Daniels and Jim Parker book "Brown Ale: History, Brewing, Techniques, Recipes.  A book I really enjoyed, so much so, I haven't given it back.

I have slightly altered today's recipe given extra ingredients I had laying around.  Just 3/4 of a pound of 2-row addition is all.

• 9.75 lbs Pale Malt (2 Row - US)
• 1.00 lb Chocolate Malt
• 0.50 lb Caramalt (80L)
• 0.25 lb Carapils 
• 0.25 lb Special Roast

With a brewhouse efficiency set at 75%, the estimates are as follows.

• 31.3 est. color (SRM)
• 1.062 est. O.G. (style 1.045-1.060)
• 1.016 est. F.G. (style 1.010-1.016)
• 6.03% ABV

In total, Beer Smith calculates this to be a 31.3 on the SRM scale.  Fairly dark brown ale.  With just a 0.50 lb of the Chocolate malt it would have been much lighter.  As this is a Texas style brown, I wanted to go all with the recipe.

The hops really dress up this beer with a nice bittering underneath with a hop aroma and taste.  

• 1.0 oz Galena (75 min)
• 0.5 oz Galena (45 min)
• 0.5 oz Willamette (15min)
• 1.0 oz Cascade (0 min)
• 1.0 oz Cascade (Dry Hop)

The Cascade addition in secondary really puts the mark on this beer.  This beer was the first beer that I had ever dry hopped and really enjoy the results of the finished product.  I am looking forward to a comparable beer this time around and hope that my guests will appreciate this one again.

Installing PHP's Pear on MacOS Lion

This blog post will cover the installation process of PHP's pear on MacOS Lion.

Googling revealed several blog posts for Leopard.  The first of which I encountered was, How To Install PEAR in Mac OS X Leopard.  The first instruction is not consistent with the version of PHP distributed with Lion, which prompted this blog article.  I received the following error:

Sorry!  Your PHP version is too new (5.3.6) for this go-pear.
Instead use http://pear.php.net/go-pear.phar for a more stable and current
version of go-pear, more suited to your PHP version.

If you are using Lion, follow these instructions for completing the installation process for pear.

The first step is downloading the pear PHAR.  Make sure that you execute this command in a directory where you have write permissions.  I chose my home directory.

curl http://pear.php.net/go-pear.phar > go-pear.phar

Next, run go-pear to complete the installation process of the library.

sudo php -q go-pear.phar

When prompted with the installation locations, change the "Installation base" setting to /usr/local/pear.  Press enter, and watch the installation complete.

As documented in the installation instructions in the posting, How To Install PEAR in Mac OS X Leopard, you will need to create the php.ini.  (I am documenting the steps here for completeness.)

Copy php.ini.default to php.ini.

sudo cp /etc/php.ini.default /etc/php.ini

Next, edit the php.ini file.

sudo vi /etc/php.ini 

Lastly, update the php.ini configuration to include following line to reference pear libraries.

include_path = ".:/usr/local/pear/share/pear"

Restart your Apache server or run your PHP script.  Everything should work as expected.