1 package Catalyst::Controller::REST;
5 Catalyst::Controller::REST - A RESTful controller
9 package Foo::Controller::Bar;
11 use base 'Catalyst::Controller::REST';
13 sub thing : Local : ActionClass('REST') { }
15 # Answer GET requests to "thing"
17 my ( $self, $c ) = @_;
19 # Return a 200 OK, with the data in entity
20 # serialized in the body
25 foo => 'is real bar-y',
30 # Answer PUT requests to "thing"
37 Catalyst::Controller::REST implements a mechanism for building
38 RESTful services in Catalyst. It does this by extending the
39 normal Catalyst dispatch mechanism to allow for different
40 subroutines to be called based on the HTTP Method requested,
41 while also transparently handling all the serialization/deserialization for
44 This is probably best served by an example. In the above
45 controller, we have declared a Local Catalyst action on
46 "sub thing", and have used the ActionClass('REST').
48 Below, we have declared "thing_GET" and "thing_PUT". Any
49 GET requests to thing will be dispatched to "thing_GET",
50 while any PUT requests will be dispatched to "thing_PUT".
52 Any unimplemented HTTP methods will be met with a "405 Method Not Allowed"
53 response, automatically containing the proper list of available methods. You
54 can override this behavior through implementing a custom
55 C<thing_not_implemented> method.
57 If you do not provide an OPTIONS handler, we will respond to any OPTIONS
58 requests with a "200 OK", populating the Allowed header automatically.
60 Any data included in C<< $c->stash->{'rest'} >> will be serialized for you.
61 The serialization format will be selected based on the content-type
62 of the incoming request. It is probably easier to use the L<STATUS HELPERS>,
63 which are described below.
65 The HTTP POST, PUT, and OPTIONS methods will all automatically deserialize the
66 contents of $c->request->body based on the requests content-type header.
67 A list of understood serialization formats is below.
69 If we do not have (or cannot run) a serializer for a given content-type, a 415
70 "Unsupported Media Type" error is generated.
72 To make your Controller RESTful, simply have it
74 use base 'Catalyst::Controller::REST';
78 Catalyst::Controller::REST will automatically serialize your
79 responses, and deserialize any POST, PUT or OPTIONS requests. It evaluates
80 which serializer to use by mapping a content-type to a Serialization module.
81 We select the content-type based on:
85 =item B<The Content-Type Header>
87 If the incoming HTTP Request had a Content-Type header set, we will use it.
89 =item B<The content-type Query Parameter>
91 If this is a GET request, you can supply a content-type query parameter.
93 =item B<Evaluating the Accept Header>
95 Finally, if the client provided an Accept header, we will evaluate
96 it and use the best-ranked choice.
100 =head1 AVAILABLE SERIALIZERS
102 A given serialization mechanism is only available if you have the underlying
103 modules installed. For example, you can't use XML::Simple if it's not already
106 In addition, each serializer has it's quirks in terms of what sorts of data
107 structures it will properly handle. L<Catalyst::Controller::REST> makes
108 no attempt to svae you from yourself in this regard. :)
112 =item C<text/x-yaml> => C<YAML::Syck>
114 Returns YAML generated by L<YAML::Syck>.
116 =item C<text/html> => C<YAML::HTML>
118 This uses L<YAML::Syck> and L<URI::Find> to generate YAML with all URLs turned
119 to hyperlinks. Only useable for Serialization.
121 =item C<text/x-json> => C<JSON::Syck>
123 Uses L<JSON::Syck> to generate JSON output
125 =item C<text/x-data-dumper> => C<Data::Serializer>
127 Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
129 =item C<text/x-data-denter> => C<Data::Serializer>
131 Uses the L<Data::Serializer> module to generate L<Data::Denter> output.
133 =item C<text/x-data-taxi> => C<Data::Serializer>
135 Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
137 =item C<application/x-storable> => C<Data::Serializer>
139 Uses the L<Data::Serializer> module to generate L<Storable> output.
141 =item C<application/x-freezethaw> => C<Data::Serializer>
143 Uses the L<Data::Serializer> module to generate L<FreezeThaw> output.
145 =item C<text/x-config-general> => C<Data::Serializer>
147 Uses the L<Data::Serializer> module to generate L<Config::General> output.
149 =item C<text/x-php-serialization> => C<Data::Serializer>
151 Uses the L<Data::Serializer> module to generate L<PHP::Serialization> output.
153 =item C<text/xml> => C<XML::Simple>
155 Uses L<XML::Simple> to generate XML output. This is probably not suitable
156 for any real heavy XML work. Due to L<XML::Simple>s requirement that the data
157 you serialize be a HASHREF, we transform outgoing data to be in the form of:
159 { data => $yourdata }
163 Uses a regular Catalyst view. For example, if you wanted to have your
164 C<text/html> and C<text/xml> views rendered by TT:
166 'text/html' => [ 'View', 'TT' ],
167 'text/xml' => [ 'View', 'XML' ],
169 Will do the trick nicely.
173 By default, L<Catalyst::Controller::REST> will return a C<415 Unsupported Media Type> response if an attempt to use an unsupported content-type is made. You
174 can ensure that something is always returned by setting the C<default> config
177 __PACKAGE__->config->{'serialize'}->{'default'} = 'YAML';
179 Would make it always fall back to YAML.
181 Implementing new Serialization formats is easy! Contributions
182 are most welcome! See L<Catalyst::Action::Serialize> and
183 L<Catalyst::Action::Deserialize> for more information.
185 =head1 CUSTOM SERIALIZERS
187 If you would like to implement a custom serializer, you should create two new
188 modules in the L<Catalyst::Action::Serialize> and
189 L<Catalyst::Action::Deserialize> namespace. Then assign your new class
190 to the content-type's you want, and you're done.
192 =head1 STATUS HELPERS
194 Since so much of REST is in using HTTP, we provide these Status Helpers.
195 Using them will ensure that you are responding with the proper codes,
196 headers, and entities.
198 These helpers try and conform to the HTTP 1.1 Specification. You can
199 refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
200 These routines are all implemented as regular subroutines, and as
201 such require you pass the current context ($c) as the first argument.
209 use base 'Catalyst::Controller';
210 use Params::Validate qw(:all);
212 __PACKAGE__->mk_accessors(qw(serialize));
216 'stash_key' => 'rest',
218 'text/html' => 'YAML::HTML',
219 'text/xml' => 'XML::Simple',
220 'text/x-yaml' => 'YAML',
221 'text/x-json' => 'JSON',
222 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
223 'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
224 'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
225 'application/x-storable' => [ 'Data::Serializer', 'Storable' ],
226 'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
227 'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
228 'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
233 sub begin : ActionClass('Deserialize') {
236 sub end : ActionClass('Serialize') {
241 Returns a "200 OK" response. Takes an "entity" to serialize.
248 radiohead => "Is a good band!",
257 my %p = validate( @_, { entity => 1, }, );
259 $c->response->status(200);
260 $self->_set_entity( $c, $p{'entity'} );
266 Returns a "201 CREATED" response. Takes an "entity" to serialize,
267 and a "location" where the created object can be found.
271 $self->status_created(
273 location => $c->req->uri->as_string,
275 radiohead => "Is a good band!",
279 In the above example, we use the requested URI as our location.
280 This is probably what you want for most PUT requests.
290 location => { type => SCALAR | OBJECT },
291 entity => { optional => 1 },
296 if ( ref( $p{'location'} ) ) {
297 $location = $p{'location'}->as_string;
299 $location = $p{'location'};
301 $c->response->status(201);
302 $c->response->header( 'Location' => $location );
303 $self->_set_entity( $c, $p{'entity'} );
307 =item status_accepted
309 Returns a "202 ACCEPTED" response. Takes an "entity" to serialize.
313 $self->status_accepted(
322 sub status_accepted {
325 my %p = validate( @_, { entity => 1, }, );
327 $c->response->status(202);
328 $self->_set_entity( $c, $p{'entity'} );
332 =item status_bad_request
334 Returns a "400 BAD REQUEST" response. Takes a "message" argument
335 as a scalar, which will become the value of "error" in the serialized
340 $self->status_bad_request(
342 message => "Cannot do what you have asked!",
347 sub status_bad_request {
350 my %p = validate( @_, { message => { type => SCALAR }, }, );
352 $c->response->status(400);
353 $c->log->debug( "Status Bad Request: " . $p{'message'} );
354 $self->_set_entity( $c, { error => $p{'message'} } );
358 =item status_not_found
360 Returns a "404 NOT FOUND" response. Takes a "message" argument
361 as a scalar, which will become the value of "error" in the serialized
366 $self->status_not_found(
368 message => "Cannot find what you were looking for!",
373 sub status_not_found {
376 my %p = validate( @_, { message => { type => SCALAR }, }, );
378 $c->response->status(404);
379 $c->log->debug( "Status Not Found: " . $p{'message'} );
380 $self->_set_entity( $c, { error => $p{'message'} } );
388 if ( defined($entity) ) {
389 $c->stash->{ $self->config->{'serialize'}->{'stash_key'} } = $entity;
396 =head1 MANUAL RESPONSES
398 If you want to construct your responses yourself, all you need to
399 do is put the object you want serialized in $c->stash->{'rest'}.
401 =head1 IMPLEMENTATION DETAILS
403 This Controller ties together L<Catalyst::Action::REST>,
404 L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>. It should be suitable for most applications. You should be aware that it:
408 =item Configures the Serialization Actions
410 This class provides a default configuration for Serialization. It is currently:
414 'stash_key' => 'rest',
416 'text/html' => 'YAML::HTML',
417 'text/xml' => 'XML::Simple',
418 'text/x-yaml' => 'YAML',
419 'text/x-json' => 'JSON',
420 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
421 'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
422 'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
423 'application/x-storable' => [ 'Data::Serializer', 'Storable'
425 'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw'
427 'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ]
429 'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
434 You can read the full set of options for this configuration block in
435 L<Catalyst::Action::Serialize>.
437 =item Sets a C<begin> and C<end> method for you
439 The C<begin> method uses L<Catalyst::Action::Deserialize>. The C<end>
440 method uses L<Catalyst::Action::Serialize>. If you want to override
441 either behavior, simply implement your own C<begin> and C<end> actions
444 my Foo::Controller::Monkey;
445 use base qw(Catalyst::Controller::REST);
449 ... do things before Deserializing ...
450 $self->NEXT::begin($c);
451 ... do things after Deserializing ...
456 ... do things before Serializing ...
457 $self->NEXT::end($c);
458 ... do things after Serializing ...
461 =head1 A MILD WARNING
463 I have code in production using L<Catalyst::Controller::REST>. That said,
464 it is still under development, and it's possible that things may change
465 between releases. I promise to not break things unneccesarily. :)
469 L<Catalyst::Action::REST>, L<Catalyst::Action::Serialize>,
470 L<Catalyst::Action::Deserialize>
472 For help with REST in general:
474 The HTTP 1.1 Spec is required reading. http://www.w3.org/Protocols/rfc2616/rfc2616.txt
476 Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
478 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
482 Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
484 Marchex, Inc. paid me while I developed this module. (http://www.marchex.com)
488 You may distribute this code under the same terms as Perl itself.