Then I looked at wikipedia for the definition of REST, and it let me down. It told me that it stood for Representational State Transfer, about the fundamentals of the idea, as it relates to Roy Fielding’s doctoral dissertation, but I didn’t find it very helpful. I was left asking:

How does this apply in the real world?

I don’t know about you guys, but for me, when a technical exploration winds up centered in academic trivia, it’s frustrating. I’m always looking for the real world implications.

I kept looking beyond wikipedia, and I now understand it’s usage with in Yahoo!, and I think it has potential implications for all - so I’ve decided to share my findings.

Here’s how REST can be used in the real world (at least my version).

Take a typical CRUD app that has to do the following:

CREATE
READ
UPDATE
DELETE

Overlay this on a typical web CRUD framework, and you have a resulting hypothetical file structure that looks like something like this:

CREATE /people/create?username=smartguy&pass=geeksforfun
READ /people/edit?id=323
UPDATE /people/update?id=323&username=smartguy&pass=geeksforfun
DELETE /people/delete?id=323

This should look familiar to all geeks. It can be handled with separate files for the different actions, or use an MVC framework with a controller that intercepts the call and redirects it to a specific action.

Now, consider the built in HTTP methods GET, PUT, POST, DELETE. We all know GET and POST. PUT and DELETE are less common, but they’ve existed since HTTP 1.1. Notice the following associations:

CREATE -> PUT
READ -> GET
UPDATE -> POST
DELETE -> DELETE

Some of you may have just had the light bulbs start to flicker. Next step. Let’s put these together! While we are at it, shorten the urls in the name of SEO. Let’s take a look at our new url structure:

CREATE - PUT /people/
READ - GET /people/323
UPDATE - POST /people/323
DELETE - DELETE /people/323

This is the first 1/3rd of REST. Using an appropriate HTTP request methods to trigger the corresponding CRUD action. Your accepting application should be checking the request method (which is available
in PHP as $_SERVER[’HTTP_REQUEST_METHOD’]) and use that to fork the appropriate action.

Now, the second component of REST is using HTTP status codes for error handling. We already have plenty of status codes built into HTTP. Let’s use them. Here’s a few samples:

200 if it worked.
403 for permission denied.
304 for not modified.
404 for an invalid id
50x for errors

More lightbulbs?

The third component of REST is handling different representations of the data. This is accomplished by specifying an extension on the request.

GET /people/323.txt
GET /people/323.csv
GET /people/323.pdf
GET /people/323.xml

The above calls would all send back the same data, but in different formats based on the extension.

And the fourth component; and this one is key; is that the same methodologies are used by all the data types.

Ie.
GET /people/323.txt
GET /stuff/323.txt
GET /things/323.txt
PUT /stuff/
DELETE /things/323.xml

So you have consistency amongst all of the data elements. They all accept a common set of actions. so that all the web services deal in the same way.

In summary, to build a RESTful web service, it should:
1) Use the GET, POST, PUT, DELETE request methods defined by HTTP to trigger the various actions
2) Take advantage of the extension that the request is using to determine the content type of the response (xml, csv, txt, jpg, etc)
3) Use HTTP status codes (200, 304, 400, 405) to indicate the status of the operation.
4) Be simple and consistent. Implement same methods for CRUDding across all data elements.

Interesting model for web services.

Some may be asking. Isn’t this just SOAP or xml-rpc? Kinda, in that they are all methodologies for implementing web services. REST relies more on HTTP methods and status codes instead of XML for triggering actions.

Additional reading that I found useful:
http://doc.opengarden.org/Articles/REST_for_the_Rest_of_Us
http://webservices.xml.com/pub/a/ws/2003/09/30/soa.html
http://www.xfront.com/REST-Web-Services.html
http://tech.groups.yahoo.com/group/rest-discuss/messages

-Nick