One of the tenants of a proper RESTful API is that every entity (for entity read resource) is addressable. Okay, good; so what does that actually mean? Well let's suppose we have an employee entity, then all the employees would be addressable at:-
http://myapp.com/employees/all
and the first name of a particular employee (say employee 42) would be addressable at
http://myapp.com/employees/42/first-name
Get it? Good. Now that's easy enough to understand but what's at http://myapp.com/employees/42/first-name/ and by that I mean if I navigated to that location from the root of the myapp.com site, what would I find? Answer: nothing, nada, not a thing. In fact, you couldn't navigate there as the address doesn't exist. Its a virtual address, just something to make us humans feel better. Our RESTful API tells us that the information we want is at this address and when we type it into the browser we get the information we need and our world goes on turning like we think it should.
However, when you stop to think about it, it is more sensible not to have anything there. I mean, you *could* have the scenario where, when a user created an employee, the system physically created the paths
http://myapp.com/employees/42/first-name
http://myapp.com/employees/42/last-name
http://myapp.com/employees/42/age
http://myapp.com/employees/42/DOB
etc
and actually wrote index.aspx files to handle the requests; then, when the employee was deleted, the system could remove them all again. However, let's face it, that kind of sucks doesn't it?
So how should we do it? Well the simple answer is to have a handler for each entity (in this case employee.aspx) that is responsible for all of the behaviour of the employee entity and then have the server rewrite the URL so that requests go to the handler. Like so:-
GET /employees/42/DOB/year-part would map to GET /handlers/employee.aspx
and employee.aspx would use the values in the form fields to search the database and return the information required. And that is how we do that in a RESTful world. Good isn't it?
What? Still here? Okay, Okay, that's how we'd do it if we were writing a RESTful API for an Apache web server, but we can't do that on IIS can we, as there's no proper URL rewriting facility? Bummer. Right now, I can almost hear Andrew Westgarth shouting "but you can do url rewriting on IIS!", which, to be fair, is true. However, you can't do extensionless url rewriting out of the box with IIS, you need a third party add on to do it.
A discussion on IIS url rewriting is beyond the scope of this post, but Scott Guthrie has a great post on the topic if you want to follow up on it.
Okay? Happy now? Good; then run along, I've got work to do, I'll see you next time. :-)