Robert Hahn: A darn good web developer

Spring Cleaning

2009-04-08T02:15:59Z

Spring Cleaning (yes, I’m back)

Um, wow. It’s been awhile since I last posted anything!

During my quiet time, I’ve been busy; I’ve had a few web contracts that I worked on at night. I went to work at a cool new company called Primal Fusion as a software developer. You’ll want to check that out!

Things have finally settled down enough that I wanted to do some serious housecleaning on my site. I was getting irritated with the blogging engine I was using (Typo), irritated about the HTML I used for the beachboy theme (it never looked fine on all browsers) and I was yearning to return to the world of static website generators.

So, this site has been redesigned and re-staged. I’ve tried as much as possible to keep the links the same, but if you’ve got a 404 on a page that used to be there, please let me know about it.

The new publishing engine is a ruby-based static site generator called nanoc, which so far I’ve been very pleased with. The system provides me with a solid set of features for building a static site, and was easy to extend with features I’ve wanted to build in.

Take the homepage for example. You’ll see a mashup of my Delicious feed, Twitter feed, and my article feed sorted in order. It was only a few lines of code to build, including caching the feeds.

As per my usual, I’ve returned to a low-key presentation – the intial launch of this site doesn’t even have any javascript!

So if you’ve been subscribed to me, thank you for waiting so long!

The Ideal REST Framework.

2007-08-17T02:11:39Z

The Ideal REST Framework.

Granted, I haven’t been spending all my time looking at everyone’s favorite framework, but from the ones I do know about, it seems really odd that we have an impedance mismatch between HTTP and the classes/methods we use in our framework. I want to spend a few posts exploring how I think a framework should be put together, so that it conforms as much as possible to REST. My code samples will be in Ruby, but I don’t see any reason why you can’t build this in any other language.

Naturally, I start where the HTTP request gets handed off to what we think of as the controller in most frameworks. It seems as though we ought to have a superclass that defines the uniform interface. It would look like this:

class HTTPResource
    def get; end
    def post; end
    def put; end
    def delete; end
    def method_missing m
        @status = 405
        "Method Not Allowed"
    end
end

With it, you would instantiate the resources you want to expose. In this case, I want to build, um, how about a Media Release administration tool, where you can add, edit, and post PRs. Let’s expose a resource called Release.

class Release < HTTPResource
  def get; end
  def put; end
  def delete; end

  private

  def post;end
end

Well, I’m sure you’re tempted to say that you can post a Release, and I’d agree with you, but I wanted to set it up this way to show you something cool: by making post private, any calls to that method would instead be handled by the superclass’ method_missing method, and return a 405 Method Not Allowed. Wow, that’s convenient.

There’s a lot of stuff missing. HTTPResource really ought to get some context together, like a collection of HTTP headers and ready access to query variables. I haven’t yet thought about how that’s going to work yet – it could be that we need instance variables, or it could be that we need classes.

But one thing I thought was pretty cool about this is that this structure seems so simple and natural, you could easily write a commandline script that included these class definitions, and manipulate your app as easily from a script as from a browser. I’m sure you could do it with other frameworks too, but it looks obvious how you’d write such a tool. That seems like a win when it comes times to write tests – just call Release.new.get, for example, and test what gets returned.

Three Methods for simulating render_component in Camping

2007-07-23T02:27:00Z

Three Methods for simulating render_component in Camping

If you have used the Camping microframework for any length of time, you might have quickly found out that there’s no feature available like render_component, which is found in Ruby on Rails. render_component allows you to call a controller method (with its associated view) for the purposes of rendering a portion of your page. For example, you might want a page that primarily displays data for one employee, and show a list of employees in a side column - ideally, you’d like the controller responsible for generating a list of employees to continue to be responsible for that, even if you’re in the controller for displaying employee data. So I ended up working out three different methods for solving this problem.

Let’s go back to my running example here: I’ve got this employee management app, where people might want to add or delete employees, and on almost every page, I need to see a list of employees’ names, each linked to their profiles, on a side column. The controller class for retrieving this list could look something like this:

class Employees < R
  def get
    @employees = Employees.find :all, :order => "name asc"
    render :employee_nav_list
  end
end

Method 1: Calling methods from other classes

My first cut at trying to build render_component was the hardest thing I had to solve. The Employees class, with its get method for generating the list was already written, so what I really wanted to do was somehow instantiate the class and call get. In my previous article, we learned that the return values of these methods are always a string; if I could somehow instantiate that class, and call its get method, then I’d have a string containing a chunk of HTML that I can store in an instance variable to be used in my current view.

Calling Employees.new.get, unfortunately, wasn’t that simple. Hints to what the Employee’s constructor looked like was kind of buried in the Camping microframework itself, and after poring over the code and testing things out, I was able to come up with the following module:

module Component_Support
  def render_component( classname, method, payload, args )
    classname.new( payload, @env, method.to_s ).send(method.to_sym, *args)
  end
end

To use this, you’d have a bit of code in your app that looks like this:

module YourApp
  include Component_Support
end

and then you’re free to call render_component wherever you like. Let’s break it down. render_component, here, takes 4 arguments:

classname: The name of the class you want to instantiate
method: The method you want to call in that class
payload: If you’re making a `GET` request, this should be empty. If you’re making a `POST` request, the payload should consist of `form-encoded` data (which typically looks like this: `name1=value&name2=value&name3=value…`)
args: These would be the regular arguments the method requires to execute, if there are any.

The body of the method instantiates the object correctly, calls the method that we’re interested in, and returns the result. If I was displaying an employee profile page, and I wanted to show that list of employees down the side, all I need to do is add the following line to my profile controller:

@employee_list = render_component(Employees, 'GET', '', '')

And I’ll have a nice fragment of HTML to include in my output.

Method 3: Define methods for sharing data

I don’t know about you, but up until recently, I built the classes in Camping using only get and post methods because I thought that was the way you were supposed to do it. It was “the rules”. It never occurred to me that I could easily add other methods if I needed to.

The thing is, it’s just a class, like any other, so if you really needed to, you could move code that’s common to both get and post methods into their own method calls and call them.

using the above code snippet, we could basically build something like this:

class Profile < R '/profile'
  def get
    # code specific to get

    @employee_list = build_emp_list

    render :profile
  end

  def post
    # code specific to post

    @employee_list = build_emp_list

    render :profile
  end

  private

  def build_emp_list
    @employees = Employees.find :all, :order => "name asc"
    render :employee_nav_list
  end
end

Method 3: Putting components in modules

As a variation on a theme, suppose you have a number of controller classes, and most of them needs to display the same type of data on a page. You’d like to be as DRY as possible, and you don’t want to use the render_component code up above – maybe because the component you want to render doesn’t properly belong to one of the controller classes. All you’d need to do is make two changes to code that looks like method 2:

move #build_emp_list into a module, along with other methods you want to re-use.
add include Your_new_modulename to the class.

Here’s an example:

module MyApp::Controllers
  module Employee_Components

    # some components defined here...

    def build_emp_list
      @employees = Employees.find :all, :order => "name asc"
      render :employee_nav_list
    end
  end

  class Profile < R '/profile'
    include Employee_Components

    def get
      # code specific to get

      @employee_list = build_emp_list

      render :profile
    end

    def post
      # code specific to post

      @employee_list = build_emp_list

      render :profile
    end
  end
end

Conclusion

So, with this article, you’re well equipped to add render_component functionality to your Camping apps, which will help in making your code more DRY. Which method you use should depend on how you can best make your code readable. If the code you want to reuse resides in a related class, then I’ve provided you with a means to instantiate that class and call the method. If the only time you require this method is in one class, define it as its own function. Otherwise, some clever module management might do the trick.

Camping Without the View

2007-07-22T02:27:16Z

Camping Without the View

It’s possible to construct a web application using the Camping microframework without using the *::Views module. Most of the time, you would be crazy to do so, since the *::Views module makes it very easy to print out HTML responses using _why’s Markaby markup engine.

There is a strong use case for not using *::Views– if you want to return data that is not supposed to be formatted as HTML (like XML or JSON), you’ll probably find that it’s more work than it really ought to be, to print out that response.

The Model-less, View-less Camping App.

That’s right. I’m going to show you a camping app that does not use either the *::Views or the *::Models modules, that is perfectly legit:

#!/usr/bin/env ruby

require 'rubygems'
require 'camping'

Camping.goes :HelloWorld

module HelloWorld::Controllers
  class Index < R '/'
    def get
      %Q(
      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
      <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
        <head><title>My small page</title></head>
      <body>
        <h1>Hello, world!</h1>
      </body>
      </html>
      )
    end
  end
end

If you save this program as hello_world.rb, then run camping hello_world.rb, it will run fine, and if you point your browser to http://localhost:3301/, you will see the friendly greeting.

What’s going on? Let’s rewrite the application to something more familiar:

#!/usr/bin/env ruby

require 'rubygems'
require 'camping'

Camping.goes :HelloWorld

module HelloWorld::Controllers
  class Index < R '/'
    def get
      render :hello_world
    end
  end
end

module HelloWorld::Views
  def hello_world
    html do
      head do
        title "My small page"
      end
      body do
        h1 "Hello, world!"
      end
    end
  end
end

If you run this hello_world.rb app, you’ll get almost the same output. There is almost no magic involved here; in the get function, we have a render statement that performs the necessary work to call the hello_world function in the HelloWorld::Views module. What’s not obvious here (except to seasoned Rubyists, I suppose) is that there is an implicit return in the hello_world function; it returns a string containing the HTML to be printed. There is also an implicit return happening in the controller, where the results of the render statement (the Hello, world page) is returned to its caller.

So the dirty secret is out: as long as the methods in your controller classes return a string, whatever is in that string is what’s going to be returned to the browser.

Why do we want to do this, again?

Most of the time, you want to use the *::Views module, because, most of the time, you want to return HTML to the browser.

Knowing what we know now, we have the ability to do a couple of useful and interesting things:

build web apps that emit alternative formats
build a render_component feature into your Camping app

I’m going to get into more of this in future articles.

Setting HTTP Response Codes with Exceptions

2007-06-22T00:24:00Z

Setting HTTP Response Codes with Exceptions

A client of mine needed an admin tool for their site: a basic file upload script. Anyone who has ever written such a script knows that there are at least a good half dozen potential failure points when writing such a thing. Experience suggests that you should check at a minimum the following types of things:

The file type of the file
The size of the file
The save path were you want to put the file (does it exist? is it a directory? Can I write to that directory?
Does the file you want to upload already exist in that location? Can I overwrite it?
etc.

For some of these tests, it may actually be pretty important to fail loudly enough for the user to notice. And of course, if we want to build RESTful web applications, it would be good to return the correct HTTP response code in a failure scenario.

While writing the script, using Camping, it suddenly occurred to me that with a bit of tooling, I could easily use Ruby’s exception handling tools to make my life easier, and to make the code maintainable. This technique can easily be applied to Rails applications too.

The setup

The Pickaxe, in its description of the Exception class, describes a #status method that is only available to the SystemExit exception. That looks like a useful idea, but I need the status baked into the base Exception class. Why? Well, if the script is going to die because a directory isn’t writable, or for some other reason I couldn’t anticipate, I need the script to return a 500 error code. Time to monkey patch Exception:

class Exception
    def status
        500
    end
end

Now let’s extend this for some other error scenarios, like a user attempting to upload a file larger than I’d like:

class ForbiddenException < RuntimeError
    def status
        403
    end
end

You should compile a big list of these exceptions into its own file and require it in your app.

In Your Application

Ok, so now you’re in Camping (or Rails), and you’ve got your file processing logic sitting in a class in the model, you have an ‘error’ view (among others) and you’re calling this code from the controller. In the model, you might have a #save method, and one of the things you’re going to do before you save your uploaded file is check the file size:

raise( ForbiddenException.new, "File Too Large!") if @file.size > 11000000

Now for the juicy bit: the controller logic:

class Index
    def Post
        file = FileUpload.new(...)

        page = :index

        begin
            @file = file.save
       rescue Exception => @e # oh, noes! my bad!
            @status = @e.status 
            page = :error
        end

        render page
    end
end

In Camping, the @status variable is reserved for setting the HTTP response code, and is smart enough to change it from 200 to 302 when you’re redirecting; that said, you can set it to other codes as we’re doing here.

And the view (the @e is being used here):

def error
    h1 "An Error has occurred"
    p @e
end

After getting this working, there’s two things I couldn’t believe:

How easy it was to get this going
That no one else thought to mention this

One of the niftiest (yes, I like to use the word nifty) things about this method is that you could catch different kinds of exceptions and customize the output accordingly:

def Post
    file = FileUpload.new(...)

    page = :index

    begin
        @file = file.save
    rescue ForbiddenException => @e # silly user!
        @status = @e.status 
        page = :forbidden_page
    rescue Exception => @e # oh, noes! my bad!
        @status = @e.status 
        page = :generic_error
    end

    render page
end

Conclusion

With only a handful of lines, I managed to create a system that easily handled error scenarios in a maintainable fashion, and passed them off to the correct view as required. Better still, I managed to easily ensure that the client was receiving the correct HTTP response code. Are there ways this could be improved still more? Let me know.

Annotated PDFs, Preview.app and Adobe Acrobat

2007-05-02T04:13:34Z

Annotated PDFs, Preview.app and Adobe Acrobat

Late tonight i annotated a PDF in Preview.app, and wanted to send it to a Windows-using colleague who uses Adobe Acrobat. Then I realized that hey: maybe Preview is the only app that can read annotations made in Preview. Would Acrobat be able to read it?

Google wouldn’t tell me. So I went and downloaded the reader to see for myself.

Rest assured: it does. Annotations made in Preview can be read in Acrobat.

A Question About Using 403 Forbidden

2007-04-12T01:51:33Z

A Question About Using 403 Forbidden

From here:

403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.

Consider the following scenario: You have a web-based application that uses HTTP Authentication, and there are URIs that authorized people may edit. Here are the sample URIs:

/shipment/9879
/shipment/form/9879

You may recognize the design of these URIs from my previous post on URI Design. The difference between the URIs is that the second one pulls up a form prepopulated with shipment 9879, whereas the first is merely a read-only representation. Assume that only HTTP Authenticated users may edit the shipment.

Consider the scenario where an authenticated user wishes to share the data on this page with a group of people, some of whom have authorization to edit the resource. An unauthorized person clicks on /shipment/form/9879 and should (correctly?) get a 403 code.

Now, the developer would very much like to make life easy for people using the site. There are a number of possible ways to resolve this:

Unauthorized users will get a 403 code, and whatever /shipment/9879 would have returned, plus an error message explaining the problem.
Unauthorized users will get a 302, redirecting to /shipment/9879; no mention of the error is logged.
Unauthorized users will get a 200, but the returned representation is identical to /shipment/9879
Unauthorized users will get a 403 code, a helpful error message, and a link to /shipment/9879
???

My gut feeling is to go with 1 or 2, saving the users a click. What do you think?

The 3 Rules of URI Design

2007-04-06T04:20:00Z

The 3 Rules of URI Design

There seems to be a problem that hasn’t been properly solved in aesthetic URI design. The problem is: How do I construct a RESTful set of URIs such that one GET request results in a read-only view of the data, and another GET request results in an editable view of the data? A key constraint on the solution: it must not rely on CSS or JavaScript, because we want the basic functionality to be available to all browsers.

Dave Thomas’ recent article on the RADAR architecture (well worth the read) is the impetus behind this article, and has crystallized some thoughts that I have about the matter. At the beginning of his article, he points to a problem: the Rails developers (or at least one of them, anyway) figured URIs of the type http://example.com/articles/1;edit was a perfectly reasonable way to request an editable representation of an article. Like Dave, I think it looks tacked on.

Joe Gregorio’s excellent series of articles discussing REST (here’s one) also has examples of URI fragments that I don’t much like, specifically /employees/1. Obviously, the pattern of plural noun followed by identifier is used by many others too.

At the core, this is simply a naming problem. RESTful URIs are nouns, because they name things. In the Rails URI example, we’ve got a verb tacked on. In Joe’s employee example, we have the notion of one thing being mashed with many things.

With that in mind, I wanted to see if there’s some kind of conceptual framework that can be employed for URI design. If I need to create a new, RESTful URI, what rules could I follow to ensure a consistent, predictable, simple design? Note that for the moment, I’m focusing entirely on representing a set of data within one mime type, in particular, HTML. Further, I’m focusing only on GETting a representation. If there’s call for it, I could try to see how this works with the other HTTP verbs.

Let’s start with some generalizations. For most things, (hence the generalization) we seem to look at pages that somehow fit the following criteria:

a list of items (products on an e-commerce site; articles in a blog)
a single item (a product, or a single article)
a form that creates or edits an item (add/edit article)

These statements can be organized into a quadrant graph:

The point of the graph is to illustrate what possibilities we could encounter when we’re surfing. If you look at any given page, they tend to fall into one of the 4 boxes. You can have a read-only representation of a list, or of a single item. You can also have an editable representation of a list or a single item. The surprise (to me) is the notion of an editable list of items, but there’s no technical reason why it can’t be done; most of the time applications are designed more to edit a single item at a time.

That said, I can’t think of a single resource that wouldn’t fit in any of the categories. Sure, sometimes you might only want to edit a particular attribute of an item, but the type of representation you’re dealing with is still an editable, single item.

Designing URIs for List-like representations

Let’s tackle URIs that would fetch a list of items. We would typically see URI fragments that look something like this:

/employees/
/articles/

That seems pretty straightforward; one would reasonably expect to see a list of employees or articles, and in RESTful apps, this is often the case. But what gets me are URI fragments that look like this:

/employees/38
/articles/5

The current convention is that those numbers somehow map to a particular article or a particular employee. While we’re used to the convention, it actually doesn’t make a whole lot of sense. I think that if you’re going to refer to /employees/, then anything past the trailing slash should also identify lists. /employees/marketing could refer to a list of employees in marketing. For references to a single employee, I would rather see this:

/employee/38
/article/5

There’s no question that we’re referring to an employee with an id of 38, or a single article with an id of 5.

Rule #1: Use plural nouns to represent lists of things; use singular nouns to represent 1 particular thing.

Designing URIs for Different Views of the Same Data

Let’s consider the following set of URIs (I’m going to go ahead and apply rule #1 right now)

/article/1;edit
/article/1

These URI fragments are readily understandable enough, and there’s obviously a lot going for the notion of human factors in URIs (strange, Google has nothing on URI Human Factors). But if you want RESTful URIs, then the verb edit has got to go.

It’s clear then that what I need to do is somehow qualify the noun in those URI fragments. /article/1 can be used to retrieve a default view of an article – likely a read-only view. If I want an editable view, I need to somehow modify the noun. Here are some approaches:

/article/editable/1
/editable/article/1
/article/form/1
/form/article/1

I’ve come up with two ways to qualify different views of an article: by adding an adjective (1 and 2), and by adding a noun (3 and 4). Either seems to work fine, and some URI fragments (2, 3) read more naturally than others.

Rule # 2: When creating alternate views of the same data, consider using compound nouns or an adjective-noun pair, depending on the problem space you’re working in. Whichever style you choose, stick with it for the entire site.

Scaling URIs for many views of the same data

Alright, if you’re willing to accept either style (because I can’t see that there’s anything to always prefer one over the other), then we should see how this applies to more complicated examples.

Consider a web application that’s used to manage information about international shipments. The amount of information that can be required to ship a package is absolutely astonishing, depending on what you want to ship where, so naturally, if someone wishes to change something in their shipment information, it would be good not to have them look at a huge page full of form fields.

If you are dealing with such a form, here’s how you might want to construct multiple editable views on the data:

/shipment/1/editable/shipping-address
/shipment/1/shipping-address/form

It should be pretty easy to guess at what’s being asked for here – we use the /1 to qualify which shipment we want to view, then further qualify what it is about that shipment we want to inspect.

Rule #3: Given a complicated object with simple parts, design your URI so that you first qualify which complicated object you need a view on, then select which view you want on the simple part.

Combining the Rules

If you consider what I’ve covered in light of the quadrant graph above, I’ve defined some rules for addressing lists vs. single items, and read-only vs. editable views. Let’s look at how they could be combined. In getting this far, I’ve already combined the rules for some situations, so some of the example URI fragments already look familiar.

Illustration of URI fragments that leverage the 3 URI Design Rules
Type of view requested	Sample URI	Suggested interpretation
Read-Only; Single Item	`/article/1`	View article ‘1’ Rule 1
Read-Only; List	`/articles/javascript`	View all javascript articles Rule 1
Editable; Single Item	`/article/form/1`	View an editable version of article ‘1’ Rules 1, 2
Editable; List	`/articles/javascript/title/form/`	View an editable list of titles for all javascript articles Rules 1, 2, 3

Conclusions

I wouldn’t be surprised if, upon looking at some of these examples, your first thought would be “is that it?” because many of the URI fragments don’t look at all that weird or new. And that’s as it should be. A lot of us who care about designing URIs are probably doing many of these things right without breaking a sweat.

And yet, we’re still left with conversations like you see in the comments of Dave Thomas’ RADAR article, and there are still a lot of people who are building websites with weird structuring conventions.

For your convenience, here are the 3 Rules of URI design in one place:

Use plural nouns to represent lists of things; use singular nouns to represent 1 particular thing.
When creating alternate views of the same data, consider using compound nouns or an adjective-noun pair, depending on the problem space you’re working in. Whichever style you choose, stick with it for the entire site.
Given a complicated object with simple parts, design your URI so that you first qualify which complicated object you need a view on, then select which view you want on the simple part.

I’m interested in your comments. I’m not married to any of this; if you can convince me that there’s a better way of structuring the problem, or a better way of solving some of these issues, I’ll be happy to modify the document accordingly. I’d like this to become a resource that people who want to follow best practices.

The Web Needs Killlfiles

2007-04-06T00:21:06Z

The Web Needs Killlfiles

Nico: “In the days of Usenet you could use a killfile.”

You can do that on the web too. Imagine a killfile service, to be set up beside OpenID services. This service will accept as input the OpenID of anyone needing to be put in the killfile, and will output, on demand, an JSON string of the contents.

Sites wishing to take advantage of that service must do a couple of things. First, allow comment posting only by people with OpenID accounts. Second, fetch the authenticated person’s killfile with JavaScript and use it to conceal from view any comment posted by persons in the killfile. The only thing you’d need to agree upon is a comment microformat.

If you want to set up a server-based filtering system, it’ll require more work, but it can be done.

Stupid idea?

CSS Naked Day

2007-04-05T11:24:53Z

CSS Naked Day

CSS Naked Day today. Don’t think about it. Just do it.