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.