From: adam Date: Mon, 20 Nov 2006 03:05:26 +0000 (+0000) Subject: Adding a README X-Git-Tag: 0.67_01~62 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Action-REST.git;a=commitdiff_plain;h=01f9819aaf3c33459ffb2c9005a32ad59eee8663 Adding a README --- diff --git a/README b/README new file mode 100644 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 , 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 --- a/TODO +++ b/TODO @@ -9,3 +9,4 @@ * More tests +* Make the different Serialization mechanisms no longer required.