1 package Catalyst::Controller::REST;
4 use namespace::autoclean;
8 Catalyst::Controller::REST - A RESTful controller
12 package Foo::Controller::Bar;
14 use namespace::autoclean;
16 BEGIN { extends 'Catalyst::Controller::REST' }
18 sub thing : Local : ActionClass('REST') { }
20 # Answer GET requests to "thing"
22 my ( $self, $c ) = @_;
24 # Return a 200 OK, with the data in entity
25 # serialized in the body
30 foo => 'is real bar-y',
35 # Answer PUT requests to "thing"
37 my ( $self, $c ) = @_;
39 $radiohead = $c->req->data->{radiohead};
41 $self->status_created(
43 location => $c->req->uri,
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 usable 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 You can also add a hash in your controller config to pass options to the json object.
150 There are two options. C<json_options> are used when decoding incoming JSON, and C<json_options_encode>
151 is used when encoding JSON for output.
153 For instance, to relax permissions when deserializing input, add:
156 json_options => { relaxed => 1 }
159 To indent the JSON output so it becomes more human readable, add:
162 json_options_encode => { indent => 1 }
166 =item * C<text/javascript> => C<JSONP>
168 If a callback=? parameter is passed, this returns javascript in the form of: $callback($serializedJSON);
170 Note - this is disabled by default as it can be a security risk if you are unaware.
172 The usual MIME types for this serialization format are: 'text/javascript', 'application/x-javascript',
173 'application/javascript'.
175 =item * C<text/x-data-dumper> => C<Data::Serializer>
177 Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
179 =item * C<text/x-data-denter> => C<Data::Serializer>
181 Uses the L<Data::Serializer> module to generate L<Data::Denter> output.
183 =item * C<text/x-data-taxi> => C<Data::Serializer>
185 Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
187 =item * C<text/x-config-general> => C<Data::Serializer>
189 Uses the L<Data::Serializer> module to generate L<Config::General> output.
191 =item * C<text/x-php-serialization> => C<Data::Serializer>
193 Uses the L<Data::Serializer> module to generate L<PHP::Serialization> output.
195 =item * C<text/xml> => C<XML::Simple>
197 Uses L<XML::Simple> to generate XML output. This is probably not suitable
198 for any real heavy XML work. Due to L<XML::Simple>s requirement that the data
199 you serialize be a HASHREF, we transform outgoing data to be in the form of:
201 { data => $yourdata }
205 Uses a regular Catalyst view. For example, if you wanted to have your
206 C<text/html> and C<text/xml> views rendered by TT, set:
210 'text/html' => [ 'View', 'TT' ],
211 'text/xml' => [ 'View', 'XML' ],
215 Your views should have a C<process> method like this:
218 my ( $self, $c, $stash_key ) = @_;
222 $output = $self->serialize( $c->stash->{$stash_key} );
226 $c->response->body( $output );
227 return 1; # important
231 my ( $self, $data ) = @_;
233 my $serialized = ... process $data here ...
240 For infinite flexibility, you can provide a callback for the
241 deserialization/serialization steps.
245 'text/xml' => [ 'Callback', { deserialize => \&parse_xml, serialize => \&render_xml } ],
249 The C<deserialize> callback is passed a string that is the body of the
250 request and is expected to return a scalar value that results from
251 the deserialization. The C<serialize> callback is passed the data
252 structure that needs to be serialized and must return a string suitable
253 for returning in the HTTP response. In addition to receiving the scalar
254 to act on, both callbacks are passed the controller object and the context
255 (i.e. C<$c>) as the second and third arguments.
259 By default, L<Catalyst::Controller::REST> will return a
260 C<415 Unsupported Media Type> response if an attempt to use an unsupported
261 content-type is made. You can ensure that something is always returned by
262 setting the C<default> config option:
264 __PACKAGE__->config(default => 'text/x-yaml');
266 would make it always fall back to the serializer plugin defined for
269 =head1 CUSTOM SERIALIZERS
271 Implementing new Serialization formats is easy! Contributions
272 are most welcome! If you would like to implement a custom serializer,
273 you should create two new modules in the L<Catalyst::Action::Serialize>
274 and L<Catalyst::Action::Deserialize> namespace. Then assign your new
275 class to the content-type's you want, and you're done.
277 See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>
278 for more information.
280 =head1 STATUS HELPERS
282 Since so much of REST is in using HTTP, we provide these Status Helpers.
283 Using them will ensure that you are responding with the proper codes,
284 headers, and entities.
286 These helpers try and conform to the HTTP 1.1 Specification. You can
287 refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
288 These routines are all implemented as regular subroutines, and as
289 such require you pass the current context ($c) as the first argument.
295 BEGIN { extends 'Catalyst::Controller' }
296 use Params::Validate qw(SCALAR OBJECT);
298 __PACKAGE__->mk_accessors(qw(serialize));
301 'stash_key' => 'rest',
303 'text/xml' => 'XML::Simple',
304 'application/json' => 'JSON',
305 'text/x-json' => 'JSON',
307 'compliance_mode' => 0,
310 sub begin : ActionClass('Deserialize') { }
312 sub end : ActionClass('Serialize') { }
316 Returns a "200 OK" response. Takes an "entity" to serialize.
323 radiohead => "Is a good band!",
332 my %p = Params::Validate::validate( @_, { entity => 1, }, );
334 $c->response->status(200);
335 $self->_set_entity( $c, $p{'entity'} );
341 Returns a "201 CREATED" response. Takes an "entity" to serialize,
342 and a "location" where the created object can be found.
346 $self->status_created(
348 location => $c->req->uri,
350 radiohead => "Is a good band!",
354 In the above example, we use the requested URI as our location.
355 This is probably what you want for most PUT requests.
362 my %p = Params::Validate::validate(
365 location => { type => SCALAR | OBJECT },
366 entity => { optional => 1 },
370 $c->response->status(201);
371 $c->response->header( 'Location' => $p{location} );
372 $self->_set_entity( $c, $p{'entity'} );
376 =item status_accepted
378 Returns a "202 ACCEPTED" response. Takes an "entity" to serialize.
379 Also takes optional "location" for queue type scenarios.
383 $self->status_accepted(
385 location => $c->req->uri,
393 sub status_accepted {
396 my %p = Params::Validate::validate(
399 location => { type => SCALAR | OBJECT, optional => 1 },
404 $c->response->status(202);
405 $c->response->header( 'Location' => $p{location} ) if exists $p{location};
406 $self->_set_entity( $c, $p{'entity'} );
410 =item status_no_content
412 Returns a "204 NO CONTENT" response.
416 sub status_no_content {
419 $c->response->status(204);
420 $self->_set_entity( $c, undef );
424 =item status_multiple_choices
426 Returns a "300 MULTIPLE CHOICES" response. Takes an "entity" to serialize, which should
427 provide list of possible locations. Also takes optional "location" for preferred choice.
431 sub status_multiple_choices {
434 my %p = Params::Validate::validate(
438 location => { type => SCALAR | OBJECT, optional => 1 },
442 $c->response->status(300);
443 $c->response->header( 'Location' => $p{location} ) if exists $p{'location'};
444 $self->_set_entity( $c, $p{'entity'} );
450 Returns a "302 FOUND" response. Takes an "entity" to serialize.
451 Also takes optional "location".
458 my %p = Params::Validate::validate(
462 location => { type => SCALAR | OBJECT, optional => 1 },
466 $c->response->status(302);
467 $c->response->header( 'Location' => $p{location} ) if exists $p{'location'};
468 $self->_set_entity( $c, $p{'entity'} );
472 =item status_bad_request
474 Returns a "400 BAD REQUEST" response. Takes a "message" argument
475 as a scalar, which will become the value of "error" in the serialized
480 $self->status_bad_request(
482 message => "Cannot do what you have asked!",
487 sub status_bad_request {
490 my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
492 $c->response->status(400);
493 $c->log->debug( "Status Bad Request: " . $p{'message'} ) if $c->debug;
494 $self->_set_entity( $c, { error => $p{'message'} } );
498 =item status_forbidden
500 Returns a "403 FORBIDDEN" response. Takes a "message" argument
501 as a scalar, which will become the value of "error" in the serialized
506 $self->status_forbidden(
508 message => "access denied",
513 sub status_forbidden {
516 my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
518 $c->response->status(403);
519 $c->log->debug( "Status Forbidden: " . $p{'message'} ) if $c->debug;
520 $self->_set_entity( $c, { error => $p{'message'} } );
524 =item status_not_found
526 Returns a "404 NOT FOUND" response. Takes a "message" argument
527 as a scalar, which will become the value of "error" in the serialized
532 $self->status_not_found(
534 message => "Cannot find what you were looking for!",
539 sub status_not_found {
542 my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
544 $c->response->status(404);
545 $c->log->debug( "Status Not Found: " . $p{'message'} ) if $c->debug;
546 $self->_set_entity( $c, { error => $p{'message'} } );
552 Returns a "41O GONE" response. Takes a "message" argument as a scalar,
553 which will become the value of "error" in the serialized response.
559 message => "The document have been deleted by foo",
567 my %p = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
569 $c->response->status(410);
570 $c->log->debug( "Status Gone " . $p{'message'} ) if $c->debug;
571 $self->_set_entity( $c, { error => $p{'message'} } );
575 =item status_see_other
577 Returns a "303 See Other" response. Takes an optional "entity" to serialize,
578 and a "location" where the client should redirect to.
582 $self->status_see_other(
584 location => $some_other_url,
586 radiohead => "Is a good band!",
592 sub status_see_other {
595 my %p = Params::Validate::validate(
598 location => { type => SCALAR | OBJECT },
599 entity => { optional => 1 },
603 $c->response->status(303);
604 $c->response->header( 'Location' => $p{location} );
605 $self->_set_entity( $c, $p{'entity'} );
611 Returns a "301 MOVED" response. Takes an "entity" to serialize, and a
612 "location" where the created object can be found.
618 location => '/somewhere/else',
620 radiohead => "Is a good band!",
629 my %p = Params::Validate::validate(
632 location => { type => SCALAR | OBJECT },
633 entity => { optional => 1 },
637 my $location = ref $p{location}
638 ? $p{location}->as_string
642 $c->response->status(301);
643 $c->response->header( Location => $location );
644 $self->_set_entity($c, $p{entity});
652 if ( defined($entity) ) {
653 $c->stash->{ $self->{'stash_key'} } = $entity;
660 =head1 MANUAL RESPONSES
662 If you want to construct your responses yourself, all you need to
663 do is put the object you want serialized in $c->stash->{'rest'}.
665 =head1 IMPLEMENTATION DETAILS
667 This Controller ties together L<Catalyst::Action::REST>,
668 L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>. It should be suitable for most applications. You should be aware that it:
672 =item Configures the Serialization Actions
674 This class provides a default configuration for Serialization. It is currently:
677 'stash_key' => 'rest',
679 'text/html' => 'YAML::HTML',
680 'text/xml' => 'XML::Simple',
681 'text/x-yaml' => 'YAML',
682 'application/json' => 'JSON',
683 'text/x-json' => 'JSON',
684 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
685 'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
686 'text/x-data-taxi' => [ 'Data::Serializer', 'Data::Taxi' ],
687 'application/x-storable' => [ 'Data::Serializer', 'Storable' ],
688 'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
689 'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
690 'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
694 You can read the full set of options for this configuration block in
695 L<Catalyst::Action::Serialize>.
697 =item Sets a C<begin> and C<end> method for you
699 The C<begin> method uses L<Catalyst::Action::Deserialize>. The C<end>
700 method uses L<Catalyst::Action::Serialize>. If you want to override
701 either behavior, simply implement your own C<begin> and C<end> actions
702 and forward to another action with the Serialize and/or Deserialize
705 package Foo::Controller::Monkey;
707 use namespace::autoclean;
709 BEGIN { extends 'Catalyst::Controller::REST' }
711 sub begin : Private {
713 ... do things before Deserializing ...
714 $c->forward('deserialize');
715 ... do things after Deserializing ...
718 sub deserialize : ActionClass('Deserialize') {}
722 ... do things before Serializing ...
723 $c->forward('serialize');
724 ... do things after Serializing ...
727 sub serialize : ActionClass('Serialize') {}
729 If you need to deserialize multipart requests (i.e. REST data in
730 one part and file uploads in others) you can do so by using the
731 L<Catalyst::Action::DeserializeMultiPart> action class.
735 =head1 A MILD WARNING
737 I have code in production using L<Catalyst::Controller::REST>. That said,
738 it is still under development, and it's possible that things may change
739 between releases. I promise to not break things unnecessarily. :)
743 L<Catalyst::Action::REST>, L<Catalyst::Action::Serialize>,
744 L<Catalyst::Action::Deserialize>
746 For help with REST in general:
748 The HTTP 1.1 Spec is required reading. http://www.w3.org/Protocols/rfc2616/rfc2616.txt
750 Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
752 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
756 See L<Catalyst::Action::REST> for authors.
760 You may distribute this code under the same terms as Perl itself.
764 __PACKAGE__->meta->make_immutable;