Mapping RESTful Resource URIs Onto URL Parameters And Server-Side Events

When I think about implementing a RESTful API, my philosophical understanding is very simple: RESTful URLs need to be mapped onto a collection of URL parameters and an event type that is processed by my ColdFusion application. This means that, at its most superficial level, a RESTful API is nothing more than a set of URLs that lay on top of an existing application. Obviously, there's a lot more to REST than that; however, when it comes to simply converting requests into responses, REST is just a layer on top of the same general approach I've been using for years.

When a request comes into the server, URL mapping commonly happen at two levels:

• The web server (ex. Apache, IIS).
• The application server (ex. ColdFusion).

My personal approach is to do most of the URL mapping at the ColdFusion level. At the web server level, I do just enough to get the request routed into the ColdFusion application; then, I let the ColdFusion application do the bulk of the parsing and mapping. I do this because it's simply easier to build and to debug. Trying to figure out why a RewriteRule or a RewriteCond (mod_rewrite) is misbehaving can be like pulling teeth. But, once I get the request into a ColdFusion context, life becomes simple.

Once I have the requested resource URI in ColdFusion, I then need to map it onto a set of URL parameters and an event type that can be processed by my Controllers. To facilitate this action, I created a new project called ResourceMapper.cfc. It's a ColdFusion component that can map resource URI patterns onto a set of captured values and an arbitrary hash.

For example, it can map the HTTP action and resource URI:

GET /blog/archive/2012/08

... onto the following collection of values:

• eventType : blog.search
• archive : true
• archiveYear : 2012
• archiveMonth : 08

This set of values is then processed by the ColdFusion application in order to render a response.

This mapping is defined in the ResourceMapper.cfc as a set of action-based configurations. For example, to define a "get" request mapping, I might have something like this:

As you can see, the resource URI can contain named groups (ie. year, month). The resource URI can also map onto a set of arbitrary name-value pairs, defined by the ColdFusion hash. If you don't define a ColdFusion hash, you can still pass in a String value which will be resolved as the "event" parameter.

To see this in action, take a look at the example from my GitHub project:

As you can see, there are two ways to define resource URI mappings: with the HTTP verb methods (ie. GET, POST, PUT, DELETE); or, with the when() method, which simply allows a single resource to be reused across multiple HTTP methods.

To "resolve" a resource URI, simply pass-in the HTTP verb and resource URI to the resolveResource() method. This method will return a structure that looks like this:

Both the URL components and the name-value pairs are combined to create the "resourceParams" collection.

If the HTTP method / resource URI combination cannot be matched to a defined pattern, NULL is returned.

Behind the scenes, each resource URI configuration gets compiled down and cached as the Java objects, java.util.regex.Pattern and java.util.regex.Matcher. This makes the pattern matching robust and incredibly fast.

... though, now that I think about it, this probably doesn't make it super thread-safe. I'll probably have to re-create the Matcher instances on each request, leaving the Pattern instances cached.

Right now, the ResourceMapper.cfc only accounts for named-groups within the resource URI. In the future, I'd like to make the mapping smarter and more robust. If you'd like to take a look at it, checkout my GitHub project.

Project: ResourceMapper.cfc on GitHub.