Adding a README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..f7175e2
--- /dev/null
+++ b/README
@@ -0,0 +1,177 @@
+NAME
+    Catalyst::Controller::REST - A RESTful controller
+
+SYNOPSIS
+        package Foo::Controller::Bar;
+
+        use base 'Catalyst::Controller::REST';
+
+        sub thing : Local : ActionClass('REST') { }
+
+        # Answer GET requests to "thing"
+        sub thing_GET {
+           my ( $self, $c ) = @_;
+     
+           # Return a 200 OK, with the data in entity
+           # serialized in the body 
+           $self->status_ok(
+                $c, 
+                entity => {
+                    some => 'data',
+                    foo  => 'is real bar-y',
+                },
+           );
+        }
+
+        # Answer PUT requests to "thing"
+        sub thing_PUT { 
+          .. some action ..
+        }
+
+DESCRIPTION
+    Catalyst::Controller::REST implements a mechanism for building RESTful
+    services in Catalyst. It does this by extending the normal Catalyst
+    dispatch mechanism to allow for different subroutines to be called based
+    on the HTTP Method requested, while also transparently handling all the
+    serialization/deserialization for you.
+
+    This is probably best served by an example. In the above controller, we
+    have declared a Local Catalyst action on "sub thing", and have used the
+    ActionClass('REST').
+
+    Below, we have declared "thing_GET" and "thing_PUT". Any GET requests to
+    thing will be dispatched to "thing_GET", while any PUT requests will be
+    dispatched to "thing_PUT".
+
+    Any unimplemented HTTP METHODS will be met with a "405 Method Not
+    Allowed" response, automatically containing the proper list of available
+    methods.
+
+    The HTTP POST, PUT, and OPTIONS methods will all automatically
+    deserialize the contents of $c->request->body based on the requests
+    content-type header. A list of understood serialization formats is
+    below.
+
+    Also included in this class are several helper methods, which will
+    automatically handle setting up proper response objects for you.
+
+    To make your Controller RESTful, simply have it
+
+      use base 'Catalyst::Controller::REST'; 
+
+SERIALIZATION
+    Catalyst::Controller::REST will automatically serialize your responses.
+    The currently implemented serialization formats are:
+
+       text/x-yaml        ->   YAML::Syck
+       text/x-data-dumper ->   Data::Serializer
+
+    By default, Catalyst::Controller::REST will use YAML as the
+    serialization format.
+
+    Implementing new Serialization formats is easy! Contributions are most
+    welcome! See Catalyst::Action::Serialize and
+    Catalyst::Action::Deserialize for more information.
+
+STATUS HELPERS
+    These helpers try and conform to the HTTP 1.1 Specification. You can
+    refer to it at: http://www.w3.org/Protocols/rfc2616/rfc2616.txt. These
+    routines are all implemented as regular subroutines, and as such require
+    you pass the current context ($c) as the first argument.
+
+    status_ok
+        Returns a "200 OK" response. Takes an "entity" to serialize.
+
+        Example:
+
+          $self->status_ok(
+            $c, 
+            entity => {
+                radiohead => "Is a good band!",
+            }
+          );
+
+    status_created
+        Returns a "201 CREATED" response. Takes an "entity" to serialize,
+        and a "location" where the created object can be found.
+
+        Example:
+
+          $self->status_created(
+            $c, 
+            location => $c->req->uri->as_string,
+            entity => {
+                radiohead => "Is a good band!",
+            }
+          );
+
+        In the above example, we use the requested URI as our location. This
+        is probably what you want for most PUT requests.
+
+    status_accepted
+        Returns a "202 ACCEPTED" response. Takes an "entity" to serialize.
+
+        Example:
+
+          $self->status_accepted(
+            $c, 
+            entity => {
+                status => "queued",
+            }
+          );
+
+    status_bad_request
+        Returns a "400 BAD REQUEST" response. Takes a "message" argument as
+        a scalar, which will become the value of "error" in the serialized
+        response.
+
+        Example:
+
+          $self->status_bad_request(
+            $c, 
+            entity => {
+                message => "Cannot do what you have asked!",
+            }
+          );
+
+    status_not_found
+        Returns a "404 NOT FOUND" response. Takes a "message" argument as a
+        scalar, which will become the value of "error" in the serialized
+        response.
+
+        Example:
+
+          $self->status_not_found(
+            $c, 
+            entity => {
+                message => "Cannot find what you were looking for!",
+            }
+          );
+
+MANUAL RESPONSES
+    If you want to construct your responses yourself, all you need to do is
+    put the object you want serialized in $c->stash->{'rest'}.
+
+SEE ALSO
+    Catalyst::Action::REST, Catalyst::Action::Serialize,
+    Catalyst::Action::Deserialize
+
+    For help with REST in general:
+
+    The HTTP 1.1 Spec is required reading.
+    http://www.w3.org/Protocols/rfc2616/rfc2616.txt
+
+    Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
+
+    The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
+
+AUTHOR
+    Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and
+    jrockway
+
+    Marchex, Inc. paid me while I developed this module.
+    (http://www.marchex.com)
+
+LICENSE
+    You may distribute this code under the same terms as Perl itself.
+

diff --git a/TODO b/TODO
index 05f4776..4284686 100644 (file)
--- a/TODO
+++ b/TODO
@@ -9,3 +9,4 @@
 
 * More tests
 
+* Make the different Serialization mechanisms no longer required.