[mod_python] providing REST style interfaces

On Jan 4, 2008 1:11 PM, David Bear <David.Bear at asu.edu> wrote:
> WOW. Thanks. This is a great descriptions on REST and the most
> understandable I've looked at. The code is the teacher.

Just be aware that my code snippet is intentionally simplisitic.
I'm trying to show the big picture ideas while leaving out many
important details.

When writting an application for real use you need to pay
attention to some other things.  In general, REST applications
are much closer to the HTTP protocol, so it is important to
become very familiar with the HTTP protocol.  Whereas SOA
services just use the bare minimum HTTP functionaility and use
it as nothing more than a message transport; REST actually tries
to use as much of the HTTP protocol functionality as possible
and in the way it was intended to be used.  Read the RFC 2616
    -- http://tools.ietf.org/html/rfc2616

First, you must be very aware of the different semantics of
all the different methods, such as the difference between a
POST and a PUT.  If you use them incorrectly it can cause all
kinds of weird problems with things like caching, proxying, etc.
You also need to be much more concious of what HTTP
result codes you return; e.g., 200, 404, 405, 304, etc.

One of the things I left out of my code is when returning
a 405 (METHOD NOT ALLOWED), you must also set
the Allow: header in the error response to be the list of
all the supported methods on that resource.  Example:

    req.err_headers_out['Allow'] = 'GET, PUT, DELETE'
    raise apache.SERVER_RETURN, apache.HTTP_METHOD_NOT_ALLOWED

You should also look for the presence of all request headers
that are like Accept-XXXX:  or  If-XXXX:.  Even if you don't
handle these complexities, you should many times return an error
such as a 406 (NOT ACCEPTABLE) if the client has requested
special semantics that you are not ready to deal with.

And a rich REST "application" could choose to implement
even more of the HTTP functionality.  The HTTP headers
(both on the request and the response) are where much of the
power comes.  It can get quite involved if you do everything,
but I've successfully done all of these using just mod_python,
so it's possible.

 * content negotiation (mulitple respresentations of the same resource)
      Using the same URL I can serve up data as HTML, JSON, or XML
 * etags (for version control, lost-update prevention, cache validation)
      Etags make up for REST being stateless
 * partial content/range requests (handling very large content)
      This is very tricky to do, but can be powerful for some things
 * content encodings and transforms
      The phyical content (bytes) may differ from the logical content
-- 
Deron Meranda