--- /dev/null
+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.
+