REST fundamentals

HTTP supports 4 request (method) types:

• Post: Intended to create a resource
• Get: Intended to retrieve a resource
• Put: Intended to update a resource
• Delete: Intended to delete a resource

However browsers typically only support Post and Get requests. Put and Delete requests have been ignored and fulfilled by abusing Post and Get. The essence of REST lies in considering the web as providing information about resources, it proposes to change the way we view URL’s from actions to requests on a resource. Actions that were once part of the URL (i.e. /products/show/1), are now expressed in the method (HTTP GET /products/1).

Why should I use REST?

The key reasons appear to be:

• As an alternative to Web Services, Messaging etc. for manipulating a resource
• A consistent approach to resource discovery

Also consider that the cost of implementing RESTful requests in Rails is no more than conventional requests.

Rails Support

Rails accommodates the lack of browser support for Put and Delete with an additional request parameter that simulates the request type.

routes.rb is the key

The core of Rails’ REST support lies in routes.rb. As always, entries here map URL’s to controllers and actions.
The following entry allows the Product model to be accessed as a RESTful resource.

map.resources :products

These entries also generate methods used to assemble URL’s in views and controllers. Based on the previous example the following methods are generated:

• products_url, products_path
• product_url(id|product), product_path(id|product)
• new_product_url, new_product_path
• edit_product_url(id|product), edit_product_path(id|product)

They can be used as follows:

• Link to list all Products

  link_to 'Products', products_path

• Form for creating a new product

  form_tag(:product, :url => products_path) do

• Form for editing a product

  form_tag(:product, :url => product_path(@product), :html => {:method => :put}) do

• Link to delete a Product

  link_to 'Delete', product_path(@product), :method => :delete

• Performing a redirect to view a Product

  redirect_to product_url(@product)

Controllers respond via respond_to

REST allows clients to request different response types. Controller actions accommodate this using respond_to. Example:

def show
  all_product = Products.find :all
  respond_to do |format|
    format.html
    format.xml render(:xml => all_products.to_xml)
  end
end

To issue a non-HTML RESTful request the URL must be a RESTful URL ending with .<desired type>. For example a XML request should end in .xml (i.e. METHOD GET /products/1.xml).

Scaffold support

Rails scaffolding supports the use of REST:

rake scripts/generate scaffold_resource <name> <field>:<type> <field>:<type>...

This command

• Creates: model, restful controller, views, migration with columns
• Edits: routes.rb for RESTful request support

I’ve read Domain-Driven Design (DDD) a couple of times now and consider it the most influential book on the way I develop software. But I’ve yet to blog about it. It’s time to change that.

Firstly, serious developers and analysts simply must read this book. It’s the sort of book I’d demand be read if I owned a software organization, though (being generous) around half of the book is applicable to Analysts.

Before I read DDD the concept of a Domain Model was somewhat fuzzy, even after reading Patterns of Enterprise Application Architecture. So often I’d seen ‘Domain Models’ purely holding state. I’d joined teams late in the game that had developed ‘intelligent’ Domain Models, but how they got there was a mystery. Questions like:

• Why had this domain concept become a class?
• Why apply this pattern in the domain layer?
• What direction are we headed with the domain model?

…the answers were never clear to me. Often one technician on the team had the answer, but I didn’t feel empowered with the knowledge to act without their consultation.

DDD hits home the importance of Domain Models and presents infinitely more information than development guidelines like ‘objects should have both state and behavior related to that state’. My most significant learning from it is an approach for distilling real world concepts into software, concepts that linger in the mind of domain experts but never crossed the divide. I won’t go into detail here, but the book presents the essence of distilling those concepts - unifying the language used across roles and, more generally, throughout the team.

It’s now a rare day when a team member’s ear won’t be ringing to the sound of me stressing the importance of modeling objects on domain principles, rather than abstract, somewhat related or technical ones. Analysts directly contribute to assembling simplified object models and are on the receiving end of questions like ‘does this concept have a name?’, ‘is there a general concept that encapsulates these things?’, ‘can we break this thing down, what do you think it’s composed of?’, ‘how would you identify each of these?’.

From a requirements perspective, it’s shifted my focus from understanding the requirements and acceptance criteria in isolation to understanding the core domain; the business of the users. According to the Kano Quality Model, customers are delighted when they discover new and useful features, stuff they wouldn’t expect to see. Immersion in the domain is key to having this capability.

From a development perspective, it’s given me techniques to aid modeling the domain in software. They focus on keeping the software simple and reducing translation time between the software and the domain. Again, I won’t spell out in detail what’s best covered by the book, but it is the kind of stuff you can start practicing immediately, the majority of it transcends languages and is bound to be relevant for many years.

The book also offers solid advice to leaders on effective team structures and subdividing teams and domains. This ground is probably less explored than other parts of the book but it’s no less important. From my experience it is used less, quite simply, because changes of that magnitude requires organizational clout that is difficult for a team to ascertain.

Here’s a brief list of observations from my DDD experiences:

• I find myself spending more time thinking, less time doing while at the same time being more productive
• I’m more proactive in engaging analysts. Emotionally there’s less of a divide between developers and analysts
• The code is more consistent and easier to navigate. You are less likely to be able identify the code of an individual
• You fear changes to the code less
• You strive to the understand the business’ problems more and focus less on simply producing software
• Design discussions are welcomed and flow naturally, there’s often less friction
• Breakthroughs, refactorings that significantly simply the implementation, come earlier rather than later

Credit where credit’s due; this book is quite simply an excellent geek read. For more info see Domain-Driven Design.

I often see Martin Fowler’s works strewn around ThoughtWorks offices and client sites. Maybe it’s an unwritten law of ThoughtWorks that the development message of the organisation is especially embodied in his works. We certainly don’t promote his works internally of externally. They just seem to crop up - no doubt it helps to be one of the most successful publishers in recent times.

Analysis Patterns, (his first publication) is however a book that I’ve never seen piled around the offices of my lifetime. I’ve only heard it whispered occasionally and referenced in DDD. In essence, it’s seemingly barely of any practical value 10 years on from publication. I’d been warned it was a heavy read; detailed, complex and confusing. Something where your attention factor tends towards zero fairly quickly.

After reading and gestation time (with a honeymoon thrown in), I can’t deny all the negatives are there.

Fowler does warn that cover-to-cover for this book doesn’t work for all. As the patterns are so domain specific, nowhere near as generic as GoF, ones ability to digest the patterns is severely dented. Still, as Fowler convinces, patterns for some domains provide insights into others - so cover-to-cover it was for me.

A painful 8 months later and I’m at the end, seemingly not much more the wiser for the effort. The content was so heavy that roughly 7 pages was, in all seriousness, my largest uninterrupted reading sequence. My re-read rate was also probably an all-time high. I guess since this publication Martin’s learnt to be terser.

But there were some highlights.
Being a tad sarcastic; the nostalgia of examples in Smalltalk, some recipes based on superseded language features/restrictions like pointers and memory management (or lack of), some extremely confusing diagrams and notations (pre UML) and the prospect of patterns maturing into libraries (an industry-wide plague at the time).
Being a tad more serious; his exploration of the design options were insightful.

Significantly the book also provides a detailed explanation of the ‘knowledge level’ mentioned but not explained in the latter chapters of DDD. The importance of this concept cannot be understated; it pervades through a fair chunk of the patterns and deserves a larger influence in everyday design. DDD certainly continues on from Martin’s discussion of the fundamentals; values and entities, associations, equality etc. all get a mention. While we’re on the subject, I’d recommend DDD above Analysis Patterns as it focuses on the generics for modern languages (maybe they were 3 years ago) and is a much simpler read. But the heart of Analysis Patterns, its focus on specific domains, strangely enough gives generic insights not captured in DDD – I guess it’s the kind of stuff you can come up with after knowledge crunching for a while. For that reason I expect it will be enduring reference for all domains I encounter – so I guess it wasn’t a fruitless exercise after all.

In all I wouldn’t recommend wading through each page as I endeavored, hoping to stumble across a serious nugget. I would recommend reading through the pre-pattern content, and gathering a sufficient enough understanding of the domains to aid future reference. Of course, mileage may vary.