root/branches/cherrypy-2.x/docs/book/xml/designchoices.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="designchoices">
    <title>Design choices</title>
    <section>
        <title>A layered API</title>
        <section>
            <title>Simple apps should not require any knowledge of HTTP</title>
            <para>At its most basic, CherryPy is designed to allow the production of simple websites
            without having to think about any of the details of HTTP. Notice we're saying HTTP (the
            transport), not HTML (the markup language)! In particular, developers should not have to
            concern themselves with:</para>
            <itemizedlist>
                <listitem>
                    <para>Responding to unpublished requests</para>
                </listitem>
                <listitem>
                    <para>Logging and notifying users appropriately when unhandled exceptions
                    occur</para>
                </listitem>
                <listitem>
                    <para>The difference between query strings and POSTed params</para>
                </listitem>
                <listitem>
                    <para>The decoding and unpacking of request headers and bodies, including file
                    uploads</para>
                </listitem>
                <listitem>
                    <para>Response status or headers</para>
                </listitem>
            </itemizedlist>
            <para>For the most part, simple "page handlers" (functions attached to
            <code>cherrypy.root</code>), should never have to refer to cherrypy at all! They receive
            params via function arguments, and return content directly. Advanced functionality is
            most often enabled via the built-in filters, which encapsulate the particulars of HTTP,
            and can be completely controlled via the config file.</para>
        </section>
        <section>
            <title>Advanced apps should have full control over (valid) HTTP output</title>
            <para>Simple apps are produced simply, but when a developer needs to step out of the
            mundane and provide real value, they should be able to leverage the complete power and
            flexibility of the HTTP specification. In general, the HTTP request and response messages
            are completely represented in the <code>cherrypy.request</code> and
            <code>.response</code> objects. At the lowest level, a developer should be able to
            generate any valid HTTP response message by modifying
            <code>cherrypy.response.status</code>, <code>.headers</code>, and/or
            <code>.body</code>.</para>
            <section>
                <title>How CherryPy relates to REST (REpresentational State Transfer)</title>
                <para>The design of HTTP itself is guided by REST, a set of principles which
                constrain its expressivity and therefore its implementation. HTTP is a transfer
                protocol which enables the exchange of representations of resources. In a RESTful
                design, clients never expect to access a resource directly; instead, they request a
                representation of that resource. For example, if a resource has both an XML and an
                HTML representation, then an HTTP/1.1 server might be expected to inspect the Accept
                request header in order to decide which representation to serve in response.</para>
                <para>It's important to clarify some terminology, here. In <ulink
                url="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">REST terms</ulink>,
                a "resource" is "any concept that might be the target of an author’s hypertext
                reference...a conceptual mapping to a set of entities, not the entity that
                corresponds to the mapping at any particular point in time". A resource is not the
                request, nor the response, in an HTTP conversation. "The resource is not the storage
                object. The resource is not a mechanism that the server uses to handle the storage
                object. The resource is a conceptual mapping — the server receives the identifier
                (which identifies the mapping) and applies it to its current mapping implementation
                (usually a combination of collection-specific deep tree traversal and/or hash tables)
                to find the currently responsible handler implementation and the handler
                implementation then selects the appropriate action+response based on the request
                content."</para>
                <para>CherryPy, therefore, does not provide REST resources, nor model them, nor serve
                them. Instead, it provides mappings between identifiers (URI's) and handlers
                (functions). It allows application developers to model resources, perhaps, but it
                only serves representations of resources.</para>
                <para>By default, these identifier-to-handler mappings (which we will call "handler
                dispatch" from now on) follow a simple pattern: since the path portion of a URI is
                hierarchical, CherryPy arranges handlers in a similar heirarchy, starting at
                cherrypy.root, and branching on each attribute; every leaf node in this tree must be
                "exposed" (but the branches need not be, see section 2.2). Note in particular that,
                although the query portion of a Request-URI is part of the resource identifier,
                CherryPy does not use it to map identifiers to handlers. Application developers may
                use the query string to further identify the requested resource, of course, but
                CherryPy, not having any domain-specific knowledge about the format or semantic of a
                query string, doesn't try to guess.</para>
                <para>Filters, then, are CherryPy's way to wrap or circumvent the default handler
                dispatch. EncodingFilter, for example, wraps the response from a handler, encoding
                the response body as it is produced. StaticFilter, on the other hand, intercepts some
                requests (based on the path portion of the Request-URI) and implements its own
                identifier-to-handler mapping. Developers who wish to provide their own handler
                dispatch mechanisms are encouraged to do so via a filter.</para>
            </section>
        </section>
    </section>
</section>