2 Catalyst::Controller::REST - A RESTful controller
5 package Foo::Controller::Bar;
7 use base 'Catalyst::Controller::REST';
9 sub thing : Local : ActionClass('REST') { }
11 # Answer GET requests to "thing"
13 my ( $self, $c ) = @_;
15 # Return a 200 OK, with the data in entity
16 # serialized in the body
21 foo => 'is real bar-y',
26 # Answer PUT requests to "thing"
32 Catalyst::Controller::REST implements a mechanism for building RESTful
33 services in Catalyst. It does this by extending the normal Catalyst
34 dispatch mechanism to allow for different subroutines to be called based
35 on the HTTP Method requested, while also transparently handling all the
36 serialization/deserialization for you.
38 This is probably best served by an example. In the above controller, we
39 have declared a Local Catalyst action on "sub thing", and have used the
42 Below, we have declared "thing_GET" and "thing_PUT". Any GET requests to
43 thing will be dispatched to "thing_GET", while any PUT requests will be
44 dispatched to "thing_PUT".
46 Any unimplemented HTTP METHODS will be met with a "405 Method Not
47 Allowed" response, automatically containing the proper list of available
50 The HTTP POST, PUT, and OPTIONS methods will all automatically
51 deserialize the contents of $c->request->body based on the requests
52 content-type header. A list of understood serialization formats is
55 Also included in this class are several helper methods, which will
56 automatically handle setting up proper response objects for you.
58 To make your Controller RESTful, simply have it
60 use base 'Catalyst::Controller::REST';
63 Catalyst::Controller::REST will automatically serialize your responses.
64 The currently implemented serialization formats are:
66 text/x-yaml -> YAML::Syck
67 text/x-data-dumper -> Data::Serializer
69 By default, Catalyst::Controller::REST will use YAML as the
72 Implementing new Serialization formats is easy! Contributions are most
73 welcome! See Catalyst::Action::Serialize and
74 Catalyst::Action::Deserialize for more information.
77 These helpers try and conform to the HTTP 1.1 Specification. You can
78 refer to it at: http://www.w3.org/Protocols/rfc2616/rfc2616.txt. These
79 routines are all implemented as regular subroutines, and as such require
80 you pass the current context ($c) as the first argument.
83 Returns a "200 OK" response. Takes an "entity" to serialize.
90 radiohead => "Is a good band!",
95 Returns a "201 CREATED" response. Takes an "entity" to serialize,
96 and a "location" where the created object can be found.
100 $self->status_created(
102 location => $c->req->uri->as_string,
104 radiohead => "Is a good band!",
108 In the above example, we use the requested URI as our location. This
109 is probably what you want for most PUT requests.
112 Returns a "202 ACCEPTED" response. Takes an "entity" to serialize.
116 $self->status_accepted(
124 Returns a "400 BAD REQUEST" response. Takes a "message" argument as
125 a scalar, which will become the value of "error" in the serialized
130 $self->status_bad_request(
133 message => "Cannot do what you have asked!",
138 Returns a "404 NOT FOUND" response. Takes a "message" argument as a
139 scalar, which will become the value of "error" in the serialized
144 $self->status_not_found(
147 message => "Cannot find what you were looking for!",
152 If you want to construct your responses yourself, all you need to do is
153 put the object you want serialized in $c->stash->{'rest'}.
156 Catalyst::Action::REST, Catalyst::Action::Serialize,
157 Catalyst::Action::Deserialize
159 For help with REST in general:
161 The HTTP 1.1 Spec is required reading.
162 http://www.w3.org/Protocols/rfc2616/rfc2616.txt
164 Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
166 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
169 Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and
172 Marchex, Inc. paid me while I developed this module.
173 (http://www.marchex.com)
176 You may distribute this code under the same terms as Perl itself.