1 package Catalyst::Controller::REST;
3 use namespace::autoclean;
6 $VERSION = eval $VERSION;
10 Catalyst::Controller::REST - A RESTful controller
14 package Foo::Controller::Bar;
16 use namespace::autoclean;
18 BEGIN { extends 'Catalyst::Controller::REST' }
20 sub thing : Local : ActionClass('REST') { }
22 # Answer GET requests to "thing"
24 my ( $self, $c ) = @_;
26 # Return a 200 OK, with the data in entity
27 # serialized in the body
32 foo => 'is real bar-y',
37 # Answer PUT requests to "thing"
39 $radiohead = $req->data->{radiohead};
41 $self->status_created(
43 location => $c->req->uri->as_string,
45 radiohead => $radiohead,
52 Catalyst::Controller::REST implements a mechanism for building
53 RESTful services in Catalyst. It does this by extending the
54 normal Catalyst dispatch mechanism to allow for different
55 subroutines to be called based on the HTTP Method requested,
56 while also transparently handling all the serialization/deserialization for
59 This is probably best served by an example. In the above
60 controller, we have declared a Local Catalyst action on
61 "sub thing", and have used the ActionClass('REST').
63 Below, we have declared "thing_GET" and "thing_PUT". Any
64 GET requests to thing will be dispatched to "thing_GET",
65 while any PUT requests will be dispatched to "thing_PUT".
67 Any unimplemented HTTP methods will be met with a "405 Method Not Allowed"
68 response, automatically containing the proper list of available methods. You
69 can override this behavior through implementing a custom
70 C<thing_not_implemented> method.
72 If you do not provide an OPTIONS handler, we will respond to any OPTIONS
73 requests with a "200 OK", populating the Allowed header automatically.
75 Any data included in C<< $c->stash->{'rest'} >> will be serialized for you.
76 The serialization format will be selected based on the content-type
77 of the incoming request. It is probably easier to use the L<STATUS HELPERS>,
78 which are described below.
80 "The HTTP POST, PUT, and OPTIONS methods will all automatically
81 L<deserialize|Catalyst::Action::Deserialize> the contents of
82 C<< $c->request->body >> into the C<< $c->request->data >> hashref", based on
83 the request's C<Content-type> header. A list of understood serialization
84 formats is L<below|/AVAILABLE SERIALIZERS>.
86 If we do not have (or cannot run) a serializer for a given content-type, a 415
87 "Unsupported Media Type" error is generated.
89 To make your Controller RESTful, simply have it
91 BEGIN { extends 'Catalyst::Controller::REST' }
95 See L<Catalyst::Action::Serialize/CONFIGURATION>. Note that the C<serialize>
96 key has been deprecated.
100 Catalyst::Controller::REST will automatically serialize your
101 responses, and deserialize any POST, PUT or OPTIONS requests. It evaluates
102 which serializer to use by mapping a content-type to a Serialization module.
103 We select the content-type based on:
107 =item B<The Content-Type Header>
109 If the incoming HTTP Request had a Content-Type header set, we will use it.
111 =item B<The content-type Query Parameter>
113 If this is a GET request, you can supply a content-type query parameter.
115 =item B<Evaluating the Accept Header>
117 Finally, if the client provided an Accept header, we will evaluate
118 it and use the best-ranked choice.
122 =head1 AVAILABLE SERIALIZERS
124 A given serialization mechanism is only available if you have the underlying
125 modules installed. For example, you can't use XML::Simple if it's not already
128 In addition, each serializer has its quirks in terms of what sorts of data
129 structures it will properly handle. L<Catalyst::Controller::REST> makes
130 no attempt to save you from yourself in this regard. :)
134 =item * C<text/x-yaml> => C<YAML::Syck>
136 Returns YAML generated by L<YAML::Syck>.
138 =item * C<text/html> => C<YAML::HTML>
140 This uses L<YAML::Syck> and L<URI::Find> to generate YAML with all URLs turned
141 to hyperlinks. Only useable for Serialization.
143 =item * C<application/json> => C<JSON>
145 Uses L<JSON> to generate JSON output. It is strongly advised to also have
146 L<JSON::XS> installed. The C<text/x-json> content type is supported but is
147 deprecated and you will receive warnings in your log.
149 =item * C<text/javascript> => C<JSONP>
151 If a callback=? parameter is passed, this returns javascript in the form of: $callback($serializedJSON);
153 =item * C<text/x-data-dumper> => C<Data::Serializer>
155 Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
157 =item * C<text/x-data-denter> => C<Data::Serializer>
159 Uses the L<Data::Serializer> module to generate L<Data::Denter> output.
161 =item * C<text/x-data-taxi> => C<Data::Serializer>
163 Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
165 =item * C<application/x-storable> => C<Data::Serializer>
167 Uses the L<Data::Serializer> module to generate L<Storable> output.
169 =item * C<application/x-freezethaw> => C<Data::Serializer>
171 Uses the L<Data::Serializer> module to generate L<FreezeThaw> output.
173 =item * C<text/x-config-general> => C<Data::Serializer>
175 Uses the L<Data::Serializer> module to generate L<Config::General> output.
177 =item * C<text/x-php-serialization> => C<Data::Serializer>
179 Uses the L<Data::Serializer> module to generate L<PHP::Serialization> output.
181 =item * C<text/xml> => C<XML::Simple>
183 Uses L<XML::Simple> to generate XML output. This is probably not suitable
184 for any real heavy XML work. Due to L<XML::Simple>s requirement that the data
185 you serialize be a HASHREF, we transform outgoing data to be in the form of:
187 { data => $yourdata }
191 Uses a regular Catalyst view. For example, if you wanted to have your
192 C<text/html> and C<text/xml> views rendered by TT, set:
196 'text/html' => [ 'View', 'TT' ],
197 'text/xml' => [ 'View', 'XML' ],
201 Your views should have a C<process> method like this:
204 my ( $self, $c, $stash_key ) = @_;
208 $output = $self->serialize( $c->stash->{$stash_key} );
212 $c->response->body( $output );
213 return 1; # important
217 my ( $self, $data ) = @_;
219 my $serialized = ... process $data here ...
226 By default, L<Catalyst::Controller::REST> will return a
227 C<415 Unsupported Media Type> response if an attempt to use an unsupported
228 content-type is made. You can ensure that something is always returned by
229 setting the C<default> config option:
231 __PACKAGE__->config(default => 'text/x-yaml');
233 would make it always fall back to the serializer plugin defined for
236 =head1 CUSTOM SERIALIZERS
238 Implementing new Serialization formats is easy! Contributions
239 are most welcome! If you would like to implement a custom serializer,
240 you should create two new modules in the L<Catalyst::Action::Serialize>
241 and L<Catalyst::Action::Deserialize> namespace. Then assign your new
242 class to the content-type's you want, and you're done.
244 See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>
245 for more information.
247 =head1 STATUS HELPERS
249 Since so much of REST is in using HTTP, we provide these Status Helpers.
250 Using them will ensure that you are responding with the proper codes,
251 headers, and entities.
253 These helpers try and conform to the HTTP 1.1 Specification. You can
254 refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
255 These routines are all implemented as regular subroutines, and as
256 such require you pass the current context ($c) as the first argument.
262 BEGIN { extends 'Catalyst::Controller' }
263 use Params::Validate qw(SCALAR OBJECT);
265 __PACKAGE__->mk_accessors(qw(serialize));
268 'stash_key' => 'rest',
270 'text/html' => 'YAML::HTML',
271 'text/xml' => 'XML::Simple',
272 'text/x-yaml' => 'YAML',
273 'application/json' => 'JSON',
274 'text/x-json' => 'JSON',
275 'application/x-javascript' => 'JSONP',
276 'application/javascript' => 'JSONP',
277 'text/javascript' => 'JSONP',
278 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
279 'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
280 'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
281 'application/x-storable' => [ 'Data::Serializer', 'Storable' ],
282 'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
283 'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
284 'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
288 sub begin : ActionClass('Deserialize') { }
290 sub end : ActionClass('Serialize') { }
294 Returns a "200 OK" response. Takes an "entity" to serialize.
301 radiohead => "Is a good band!",
310 my %p = Params::Validate::validate( @_, { entity => 1, }, );
312 $c->response->status(200);
313 $self->_set_entity( $c, $p{'entity'} );
319 Returns a "201 CREATED" response. Takes an "entity" to serialize,
320 and a "location" where the created object can be found.
324 $self->status_created(
326 location => $c->req->uri->as_string,
328 radiohead => "Is a good band!",
332 In the above example, we use the requested URI as our location.
333 This is probably what you want for most PUT requests.
340 my %p = Params::Validate::validate(
343 location => { type => SCALAR | OBJECT },
344 entity => { optional => 1 },
349 if ( ref( $p{'location'} ) ) {
350 $location = $p{'location'}->as_string;
352 $location = $p{'location'};
354 $c->response->status(201);
355 $c->response->header( 'Location' => $location );
356 $self->_set_entity( $c, $p{'entity'} );
360 =item status_accepted
362 Returns a "202 ACCEPTED" response. Takes an "entity" to serialize.
366 $self->status_accepted(
375 sub status_accepted {
378 my %p = Params::Validate::validate( @_, { entity => 1, }, );
380 $c->response->status(202);
381 $self->_set_entity( $c, $p{'entity'} );
385 =item status_no_content
387 Returns a "204 NO CONTENT" response.
391 sub status_no_content {
394 $c->response->status(204);
395 $self->_set_entity( $c, undef );
399 =item status_bad_request
401 Returns a "400 BAD REQUEST" response. Takes a "message" argument
402 as a scalar, which will become the value of "error" in the serialized
407 $self->status_bad_request(
409 message => "Cannot do what you have asked!",
414 sub status_bad_request {
417 my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
419 $c->response->status(400);
420 $c->log->debug( "Status Bad Request: " . $p{'message'} ) if $c->debug;
421 $self->_set_entity( $c, { error => $p{'message'} } );
425 =item status_not_found
427 Returns a "404 NOT FOUND" response. Takes a "message" argument
428 as a scalar, which will become the value of "error" in the serialized
433 $self->status_not_found(
435 message => "Cannot find what you were looking for!",
440 sub status_not_found {
443 my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
445 $c->response->status(404);
446 $c->log->debug( "Status Not Found: " . $p{'message'} ) if $c->debug;
447 $self->_set_entity( $c, { error => $p{'message'} } );
453 Returns a "41O GONE" response. Takes a "message" argument as a scalar,
454 which will become the value of "error" in the serialized response.
460 message => "The document have been deleted by foo",
468 my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
470 $c->response->status(410);
471 $c->log->debug( "Status Gone " . $p{'message'} ) if $c->debug;
472 $self->_set_entity( $c, { error => $p{'message'} } );
480 if ( defined($entity) ) {
481 $c->stash->{ $self->{'stash_key'} } = $entity;
488 =head1 MANUAL RESPONSES
490 If you want to construct your responses yourself, all you need to
491 do is put the object you want serialized in $c->stash->{'rest'}.
493 =head1 IMPLEMENTATION DETAILS
495 This Controller ties together L<Catalyst::Action::REST>,
496 L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>. It should be suitable for most applications. You should be aware that it:
500 =item Configures the Serialization Actions
502 This class provides a default configuration for Serialization. It is currently:
505 'stash_key' => 'rest',
507 'text/html' => 'YAML::HTML',
508 'text/xml' => 'XML::Simple',
509 'text/x-yaml' => 'YAML',
510 'application/json' => 'JSON',
511 'text/x-json' => 'JSON',
512 'application/x-javascript' => 'JSONP',
513 'application/javascript' => 'JSONP',
514 'text/javascript' => 'JSONP',
515 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
516 'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
517 'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
518 'application/x-storable' => [ 'Data::Serializer', 'Storable' ],
519 'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
520 'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
521 'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
525 You can read the full set of options for this configuration block in
526 L<Catalyst::Action::Serialize>.
528 =item Sets a C<begin> and C<end> method for you
530 The C<begin> method uses L<Catalyst::Action::Deserialize>. The C<end>
531 method uses L<Catalyst::Action::Serialize>. If you want to override
532 either behavior, simply implement your own C<begin> and C<end> actions
535 package Foo::Controller::Monkey;
537 use namespace::autoclean;
539 BEGIN { extends 'Catalyst::Controller::REST' }
543 ... do things before Deserializing ...
544 $self->maybe::next::method($c);
545 ... do things after Deserializing ...
550 ... do things before Serializing ...
551 $self->maybe::next::method($c);
552 ... do things after Serializing ...
557 =head1 A MILD WARNING
559 I have code in production using L<Catalyst::Controller::REST>. That said,
560 it is still under development, and it's possible that things may change
561 between releases. I promise to not break things unneccesarily. :)
565 L<Catalyst::Action::REST>, L<Catalyst::Action::Serialize>,
566 L<Catalyst::Action::Deserialize>
568 For help with REST in general:
570 The HTTP 1.1 Spec is required reading. http://www.w3.org/Protocols/rfc2616/rfc2616.txt
572 Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
574 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
578 See L<Catalyst::Action::REST> for authors.
582 You may distribute this code under the same terms as Perl itself.