Woke up this morning to find this totally awesome comment in regards to my post on PUT vs. POST, a rather old entry I made about REST:

Jonnay, I totally agree that a direct filesystem->URL structure mapping is simple, convenient, and effective -- for websites.

However, the definition of "website" is evolving, or fragmenting, or something -- I don't know! As I see it, the WWW was originally a document publishing system. Then it sprouted a new type of software platform -- which was shoehorned onto a publishing system. So then a website was either a collection of documents or a software application structured like a collection of documents - or both at the same time.

So it's only natural that we have a lot of uncertainty and befuddlement about what the hell is going on.

I see the development of REST applications as a clear way to use the WWW as a software platform, distinct from a website comprised of documents.

With these new REST applications, which really aren't "websites" as we know them -- although they can contain and serve documents, the application is more than a collection of documents -- I've found that the best thing we can do to fully realize their potential is to decouple them from our internal conceptual model of a "website" and think of them as a new kind of entity.

So, now we have this new entity: a REST application. It can be thought of as a tree/collection of resources contained in a single root resource, each of which can contain child resources of their own. As you know, a URL structure can be mapped the same way, as can a filesystem. So what's the problem?

Methods!

In a REST application, as you know, most resources will support 2-4 of the "major" HTTP methods. For instance, "/users" will probably support GET and POST. "/users/avi" will probably support GET, PUT, and DELETE, and maybe POST too.

OK, so what? Couldn't we have a single file for each resource, which would be coded to detect which method was specified, and take the proper action and return the proper response?

Sure we could. But I see two problems with that approach:

(1) This is a little too similar to a conventional website. That's fine for a conventional website, but when constructing a REST application, it's important that we disassociate it from our conceptual model of what a website is. When we see users.php and user.php, it will line up with our conceptual model of a website, where most resources are intented[sic] to support only GET, with a few supporting POST. This may seem silly, but I think it's the only way for us to realize the full potential of this new application architecture without being hampered by past conventions.

(2)There's a strong possibility of a lot of code duplication happening, without much reuse. I suppose this could be avoided by encapsulating the behavior[sic] in classes, but there are still a lot of files to deal with, and a lot of code scattered around. It just feels a bit messy to me.

... so, in my current project, I've abstracted resources into application concepts that a central request handler processes and returns the appropriate response/representation.

I suppose there could be a middle ground, though: some fancy HTACCESS mod_rewrite magic could enable a structure like this:

/wwwroot/resources/users/get.php
/wwwroot/resources/users/post.php
/wwwroot/resources/users/user/get.php
/wwwroot/resources/users/user/put.php
/wwwroot/resources/users/user/delete.php

and so on. Again there are a lot of files and shared libraries would be necessary to reduce code duplication, but it would probably work fairly well. However, I personally wouldn't want to have the job of writing all those mod_rewrite rules.

Whew, I think that's quite enough for now! I am *done*!

So, I am going to respond to it. Not as a refutation or anything of the sort, but as a continuation of of the original conversation, because it is helping me with my understanding of how to represent resources in a RESTful system.

I think that going back to the ancient history of the WWW, and remembering the document retrieval roots of the system is very important. And for awhile there a software platform was shoe horned (and still is shoehorned) onto this document structure. But this is exactly where I believe REST comes in, because it takes the document structure and abstracts it from documents being acted upon, to resources being acted upon. A resource can still be a document, or it can be a bookmark, a user account, even a "transaction object". So trying to make the distinction between documents and resources is possible, but it is like making the distinction between an orange and a fruit.

So I don't think you can use REST and say it is distinct from a website as a collection of documents. I think you can say that you can use REST and say it is distinct from how we generally structure our websites today. But REST is an extension of the document storage and retrieval system laid out so long ago, that harnesses the existing infrastructure that is in pplace.

In regards to issue 1, don't know that it is really an issue. The point of REST is that you are constrained by the architecture already laid out by HTTP. So yes, it is going to look, and act like a conventional website. Thats where the power in HTTP lies, so lets use it. In fact, REST is a set of architectural constraints.

In regards to issue 2, that is the rub. I want to have a filesystem->resource mapping because I believe it will cut down on confusion, make the code easier to read, and contains inherent organization. You believe that it will result in classes spread everywhere, and lots of confusion.

I think the key here is to already have a good idea of what you are trying to achieve with your application before you actually go out and write it. You really hit the nail on the head when you said " I've abstracted resources into application concepts that a central request handler processes and returns the appropriate response/representation.". And I think the middle-ground between a filesystem mapping of resources, and code sanity can be maintained.

If a resource is just an abstraction of a document, then what is the abstraction of a directory? A request handler! Was the choice of words specific? Because that is the KEY class inside of My Meditation project. Anyway, all I am advocating is a decentralized request handler, rather then a centralized one. The MyRestSql Table resource is an example of what I am talking about (in fact, it needs to be refactored a little bit so that it follows your collection example, but I digress). If I ever decided to allow access to databases RESTfully, I wouldn't overload the table.php resource container, but I would make a different resource container all together.

Paul James, author of the Tonic framework had a look at my work on Meditation and he noticed exactly that, Meditation was focused on the handling of requests, rather then resources.

As an aside, having a deep look at Tonic is something I simply must do. Not just to be a good citizen and reciprocate, but also for what I could potentially learn from it.