| | 48 | <section> |
|---|
| | 49 | <title>How CherryPy relates to REST (REpresentational State Transfer)</title> |
|---|
| | 50 | <para>The design of HTTP itself is guided by REST, a set of principles which |
|---|
| | 51 | constrain its expressivity and therefore its implementation. HTTP is a transfer |
|---|
| | 52 | protocol which enables the exchange of representations of resources. In a RESTful |
|---|
| | 53 | design, clients never expect to access a resource directly; instead, they request a |
|---|
| | 54 | representation of that resource. For example, if a resource has both an XML and an |
|---|
| | 55 | HTML representation, then an HTTP/1.1 server might be expected to inspect the Accept |
|---|
| | 56 | request header in order to decide which representation to serve in response.</para> |
|---|
| | 57 | <para>It's important to clarify some terminology, here. In <ulink |
|---|
| | 58 | url="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">REST terms</ulink>, |
|---|
| | 59 | a "resource" is "any concept that might be the target of an author’s hypertext |
|---|
| | 60 | reference...a conceptual mapping to a set of entities, not the entity that |
|---|
| | 61 | corresponds to the mapping at any particular point in time". A resource is not the |
|---|
| | 62 | request, nor the response, in an HTTP conversation. "The resource is not the storage |
|---|
| | 63 | object. The resource is not a mechanism that the server uses to handle the storage |
|---|
| | 64 | object. The resource is a conceptual mapping — the server receives the identifier |
|---|
| | 65 | (which identifies the mapping) and applies it to its current mapping implementation |
|---|
| | 66 | (usually a combination of collection-specific deep tree traversal and/or hash tables) |
|---|
| | 67 | to find the currently responsible handler implementation and the handler |
|---|
| | 68 | implementation then selects the appropriate action+response based on the request |
|---|
| | 69 | content."</para> |
|---|
| | 70 | <para>CherryPy, therefore, does not provide REST resources, nor model them, nor serve |
|---|
| | 71 | them. Instead, it provides mappings between identifiers (URI's) and handlers |
|---|
| | 72 | (functions). It allows application developers to model resources, perhaps, but it |
|---|
| | 73 | only serves representations of resources.</para> |
|---|
| | 74 | <para>By default, these identifier-to-handler mappings (which we will call "handler |
|---|
| | 75 | dispatch" from now on) follow a simple pattern: since the path portion of a URI is |
|---|
| | 76 | hierarchical, CherryPy arranges handlers in a similar heirarchy, starting at |
|---|
| | 77 | cherrypy.root, and branching on each attribute; every leaf node in this tree must be |
|---|
| | 78 | "exposed" (but the branches need not be, see section 2.2). Note in particular that, |
|---|
| | 79 | although the query portion of a Request-URI is part of the resource identifier, |
|---|
| | 80 | CherryPy does not use it to map identifiers to handlers. Application developers may |
|---|
| | 81 | use the query string to further identify the requested resource, of course, but |
|---|
| | 82 | CherryPy, not having any domain-specific knowledge about the format or semantic of a |
|---|
| | 83 | query string, doesn't try to guess.</para> |
|---|
| | 84 | <para>Filters, then, are CherryPy's way to wrap or circumvent the default handler |
|---|
| | 85 | dispatch. EncodingFilter, for example, wraps the response from a handler, encoding |
|---|
| | 86 | the response body as it is produced. StaticFilter, on the other hand, intercepts some |
|---|
| | 87 | requests (based on the path portion of the Request-URI) and implements its own |
|---|
| | 88 | identifier-to-handler mapping. Developers who wish to provide their own handler |
|---|
| | 89 | dispatch mechanisms are encouraged to do so via a filter.</para> |
|---|
| | 90 | </section> |
|---|
