lib/Catalyst/Controller/REST.pm

   1 package Catalyst::Controller::REST;
   2 use strict;
   3 use warnings;
   4
   5 our $VERSION = '0.75';
   6 $VERSION = eval $VERSION;
   7
   8 =head1 NAME
   9
  10 Catalyst::Controller::REST - A RESTful controller
  11
  12 =head1 SYNOPSIS
  13
  14     package Foo::Controller::Bar;
  15
  16     use base 'Catalyst::Controller::REST';
  17
  18     sub thing : Local : ActionClass('REST') { }
  19
  20     # Answer GET requests to "thing"
  21     sub thing_GET {
  22        my ( $self, $c ) = @_;
  23
  24        # Return a 200 OK, with the data in entity
  25        # serialized in the body
  26        $self->status_ok(
  27             $c,
  28             entity => {
  29                 some => 'data',
  30                 foo  => 'is real bar-y',
  31             },
  32        );
  33     }
  34
  35     # Answer PUT requests to "thing"
  36     sub thing_PUT {
  37       .. some action ..
  38     }
  39
  40 =head1 DESCRIPTION
  41
  42 Catalyst::Controller::REST implements a mechanism for building
  43 RESTful services in Catalyst.  It does this by extending the
  44 normal Catalyst dispatch mechanism to allow for different
  45 subroutines to be called based on the HTTP Method requested,
  46 while also transparently handling all the serialization/deserialization for
  47 you.
  48
  49 This is probably best served by an example.  In the above
  50 controller, we have declared a Local Catalyst action on
  51 "sub thing", and have used the ActionClass('REST').
  52
  53 Below, we have declared "thing_GET" and "thing_PUT".  Any
  54 GET requests to thing will be dispatched to "thing_GET",
  55 while any PUT requests will be dispatched to "thing_PUT".
  56
  57 Any unimplemented HTTP methods will be met with a "405 Method Not Allowed"
  58 response, automatically containing the proper list of available methods.  You
  59 can override this behavior through implementing a custom
  60 C<thing_not_implemented> method.
  61
  62 If you do not provide an OPTIONS handler, we will respond to any OPTIONS
  63 requests with a "200 OK", populating the Allowed header automatically.
  64
  65 Any data included in C<< $c->stash->{'rest'} >> will be serialized for you.
  66 The serialization format will be selected based on the content-type
  67 of the incoming request.  It is probably easier to use the L<STATUS HELPERS>,
  68 which are described below.
  69
  70 The HTTP POST, PUT, and OPTIONS methods will all automatically deserialize the
  71 contents of $c->request->body based on the requests content-type header.
  72 A list of understood serialization formats is below.
  73
  74 If we do not have (or cannot run) a serializer for a given content-type, a 415
  75 "Unsupported Media Type" error is generated.
  76
  77 To make your Controller RESTful, simply have it
  78
  79   use base 'Catalyst::Controller::REST';
  80
  81 =head1 SERIALIZATION
  82
  83 Catalyst::Controller::REST will automatically serialize your
  84 responses, and deserialize any POST, PUT or OPTIONS requests. It evaluates
  85 which serializer to use by mapping a content-type to a Serialization module.
  86 We select the content-type based on:
  87
  88 =over 2
  89
  90 =item B<The Content-Type Header>
  91
  92 If the incoming HTTP Request had a Content-Type header set, we will use it.
  93
  94 =item B<The content-type Query Parameter>
  95
  96 If this is a GET request, you can supply a content-type query parameter.
  97
  98 =item B<Evaluating the Accept Header>
  99
 100 Finally, if the client provided an Accept header, we will evaluate
 101 it and use the best-ranked choice.
 102
 103 =back
 104
 105 =head1 AVAILABLE SERIALIZERS
 106
 107 A given serialization mechanism is only available if you have the underlying
 108 modules installed.  For example, you can't use XML::Simple if it's not already
 109 installed.
 110
 111 In addition, each serializer has it's quirks in terms of what sorts of data
 112 structures it will properly handle.  L<Catalyst::Controller::REST> makes
 113 no attempt to save you from yourself in this regard. :)
 114
 115 =over 2
 116
 117 =item C<text/x-yaml> => C<YAML::Syck>
 118
 119 Returns YAML generated by L<YAML::Syck>.
 120
 121 =item C<text/html> => C<YAML::HTML>
 122
 123 This uses L<YAML::Syck> and L<URI::Find> to generate YAML with all URLs turned
 124 to hyperlinks.  Only useable for Serialization.
 125
 126 =item C<application/json> => C<JSON>
 127
 128 Uses L<JSON> to generate JSON output.  It is strongly advised to also have
 129 L<JSON::XS> installed.  The C<text/x-json> content type is supported but is
 130 deprecated and you will receive warnings in your log.
 131
 132 =item C<text/x-data-dumper> => C<Data::Serializer>
 133
 134 Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
 135
 136 =item C<text/x-data-denter> => C<Data::Serializer>
 137
 138 Uses the L<Data::Serializer> module to generate L<Data::Denter> output.
 139
 140 =item C<text/x-data-taxi> => C<Data::Serializer>
 141
 142 Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
 143
 144 =item C<application/x-storable> => C<Data::Serializer>
 145
 146 Uses the L<Data::Serializer> module to generate L<Storable> output.
 147
 148 =item C<application/x-freezethaw> => C<Data::Serializer>
 149
 150 Uses the L<Data::Serializer> module to generate L<FreezeThaw> output.
 151
 152 =item C<text/x-config-general> => C<Data::Serializer>
 153
 154 Uses the L<Data::Serializer> module to generate L<Config::General> output.
 155
 156 =item C<text/x-php-serialization> => C<Data::Serializer>
 157
 158 Uses the L<Data::Serializer> module to generate L<PHP::Serialization> output.
 159
 160 =item C<text/xml> => C<XML::Simple>
 161
 162 Uses L<XML::Simple> to generate XML output.  This is probably not suitable
 163 for any real heavy XML work. Due to L<XML::Simple>s requirement that the data
 164 you serialize be a HASHREF, we transform outgoing data to be in the form of:
 165
 166   { data => $yourdata }
 167
 168 =item L<View>
 169
 170 Uses a regular Catalyst view.  For example, if you wanted to have your
 171 C<text/html> and C<text/xml> views rendered by TT:
 172
 173   'text/html' => [ 'View', 'TT' ],
 174   'text/xml'  => [ 'View', 'XML' ],
 175
 176 Will do the trick nicely.
 177
 178 =back
 179
 180 By default, L<Catalyst::Controller::REST> will return a C<415 Unsupported Media Type>
 181 response if an attempt to use an unsupported content-type is made.  You
 182 can ensure that something is always returned by setting the C<default>
 183 config option:
 184
 185   __PACKAGE__->config->{'default'} = 'text/x-yaml';
 186
 187 Would make it always fall back to the serializer plugin defined for text/x-yaml.
 188
 189 Implementing new Serialization formats is easy!  Contributions
 190 are most welcome!  See L<Catalyst::Action::Serialize> and
 191 L<Catalyst::Action::Deserialize> for more information.
 192
 193 =head1 CUSTOM SERIALIZERS
 194
 195 If you would like to implement a custom serializer, you should create two new
 196 modules in the L<Catalyst::Action::Serialize> and
 197 L<Catalyst::Action::Deserialize> namespace.  Then assign your new class
 198 to the content-type's you want, and you're done.
 199
 200 =head1 STATUS HELPERS
 201
 202 Since so much of REST is in using HTTP, we provide these Status Helpers.
 203 Using them will ensure that you are responding with the proper codes,
 204 headers, and entities.
 205
 206 These helpers try and conform to the HTTP 1.1 Specification.  You can
 207 refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
 208 These routines are all implemented as regular subroutines, and as
 209 such require you pass the current context ($c) as the first argument.
 210
 211 =over 4
 212
 213 =cut
 214
 215 use base 'Catalyst::Controller';
 216 use Params::Validate qw(SCALAR OBJECT);
 217
 218 __PACKAGE__->mk_accessors(qw(serialize));
 219
 220 __PACKAGE__->config(
 221     'stash_key' => 'rest',
 222     'map'       => {
 223         'text/html'          => 'YAML::HTML',
 224         'text/xml'           => 'XML::Simple',
 225         'text/x-yaml'        => 'YAML',
 226         'application/json'   => 'JSON',
 227         'text/x-json'        => 'JSON',
 228         'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
 229         'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
 230         'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
 231         'application/x-storable'    => [ 'Data::Serializer', 'Storable'     ],
 232         'application/x-freezethaw'  => [ 'Data::Serializer', 'FreezeThaw'   ],
 233         'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ],
 234         'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
 235     },
 236 );
 237
 238 sub begin : ActionClass('Deserialize') { }
 239
 240 sub end : ActionClass('Serialize') { }
 241
 242 =item status_ok
 243
 244 Returns a "200 OK" response.  Takes an "entity" to serialize.
 245
 246 Example:
 247
 248   $self->status_ok(
 249     $c,
 250     entity => {
 251         radiohead => "Is a good band!",
 252     }
 253   );
 254
 255 =cut
 256
 257 sub status_ok {
 258     my $self = shift;
 259     my $c    = shift;
 260     my %p    = Params::Validate::validate( @_, { entity => 1, }, );
 261
 262     $c->response->status(200);
 263     $self->_set_entity( $c, $p{'entity'} );
 264     return 1;
 265 }
 266
 267 =item status_created
 268
 269 Returns a "201 CREATED" response.  Takes an "entity" to serialize,
 270 and a "location" where the created object can be found.
 271
 272 Example:
 273
 274   $self->status_created(
 275     $c,
 276     location => $c->req->uri->as_string,
 277     entity => {
 278         radiohead => "Is a good band!",
 279     }
 280   );
 281
 282 In the above example, we use the requested URI as our location.
 283 This is probably what you want for most PUT requests.
 284
 285 =cut
 286
 287 sub status_created {
 288     my $self = shift;
 289     my $c    = shift;
 290     my %p    = Params::Validate::validate(
 291         @_,
 292         {
 293             location => { type     => SCALAR | OBJECT },
 294             entity   => { optional => 1 },
 295         },
 296     );
 297
 298     my $location;
 299     if ( ref( $p{'location'} ) ) {
 300         $location = $p{'location'}->as_string;
 301     } else {
 302         $location = $p{'location'};
 303     }
 304     $c->response->status(201);
 305     $c->response->header( 'Location' => $location );
 306     $self->_set_entity( $c, $p{'entity'} );
 307     return 1;
 308 }
 309
 310 =item status_accepted
 311
 312 Returns a "202 ACCEPTED" response.  Takes an "entity" to serialize.
 313
 314 Example:
 315
 316   $self->status_accepted(
 317     $c,
 318     entity => {
 319         status => "queued",
 320     }
 321   );
 322
 323 =cut
 324
 325 sub status_accepted {
 326     my $self = shift;
 327     my $c    = shift;
 328     my %p    = Params::Validate::validate( @_, { entity => 1, }, );
 329
 330     $c->response->status(202);
 331     $self->_set_entity( $c, $p{'entity'} );
 332     return 1;
 333 }
 334
 335 =item status_bad_request
 336
 337 Returns a "400 BAD REQUEST" response.  Takes a "message" argument
 338 as a scalar, which will become the value of "error" in the serialized
 339 response.
 340
 341 Example:
 342
 343   $self->status_bad_request(
 344     $c,
 345     message => "Cannot do what you have asked!",
 346   );
 347
 348 =cut
 349
 350 sub status_bad_request {
 351     my $self = shift;
 352     my $c    = shift;
 353     my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
 354
 355     $c->response->status(400);
 356     $c->log->debug( "Status Bad Request: " . $p{'message'} ) if $c->debug;
 357     $self->_set_entity( $c, { error => $p{'message'} } );
 358     return 1;
 359 }
 360
 361 =item status_not_found
 362
 363 Returns a "404 NOT FOUND" response.  Takes a "message" argument
 364 as a scalar, which will become the value of "error" in the serialized
 365 response.
 366
 367 Example:
 368
 369   $self->status_not_found(
 370     $c,
 371     message => "Cannot find what you were looking for!",
 372   );
 373
 374 =cut
 375
 376 sub status_not_found {
 377     my $self = shift;
 378     my $c    = shift;
 379     my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
 380
 381     $c->response->status(404);
 382     $c->log->debug( "Status Not Found: " . $p{'message'} ) if $c->debug;
 383     $self->_set_entity( $c, { error => $p{'message'} } );
 384     return 1;
 385 }
 386
 387 sub _set_entity {
 388     my $self   = shift;
 389     my $c      = shift;
 390     my $entity = shift;
 391     if ( defined($entity) ) {
 392         $c->stash->{ $self->{'stash_key'} } = $entity;
 393     }
 394     return 1;
 395 }
 396
 397 =back
 398
 399 =head1 MANUAL RESPONSES
 400
 401 If you want to construct your responses yourself, all you need to
 402 do is put the object you want serialized in $c->stash->{'rest'}.
 403
 404 =head1 IMPLEMENTATION DETAILS
 405
 406 This Controller ties together L<Catalyst::Action::REST>,
 407 L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>.  It should be suitable for most applications.  You should be aware that it:
 408
 409 =over 4
 410
 411 =item Configures the Serialization Actions
 412
 413 This class provides a default configuration for Serialization.  It is currently:
 414
 415   __PACKAGE__->config(
 416       serialize => {
 417          'stash_key' => 'rest',
 418          'map'       => {
 419             'text/html'          => 'YAML::HTML',
 420             'text/xml'           => 'XML::Simple',
 421             'text/x-yaml'        => 'YAML',
 422             'application/json'   => 'JSON',
 423             'text/x-json'        => 'JSON',
 424             'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
 425             'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
 426             'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
 427             'application/x-storable'    => [ 'Data::Serializer', 'Storable'
 428 ],
 429             'application/x-freezethaw'  => [ 'Data::Serializer', 'FreezeThaw'
 430 ],
 431             'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ]
 432 ,
 433             'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
 434           },
 435       }
 436   );
 437
 438 You can read the full set of options for this configuration block in
 439 L<Catalyst::Action::Serialize>.
 440
 441 =item Sets a C<begin> and C<end> method for you
 442
 443 The C<begin> method uses L<Catalyst::Action::Deserialize>.  The C<end>
 444 method uses L<Catalyst::Action::Serialize>.  If you want to override
 445 either behavior, simply implement your own C<begin> and C<end> actions
 446 and use MRO::Compat:
 447
 448   my Foo::Controller::Monkey;
 449   use base qw(Catalyst::Controller::REST);
 450
 451   sub begin :Private {
 452     my ($self, $c) = @_;
 453     ... do things before Deserializing ...
 454     $self->maybe::next::method($c);
 455     ... do things after Deserializing ...
 456   }
 457
 458   sub end :Private {
 459     my ($self, $c) = @_;
 460     ... do things before Serializing ...
 461     $self->maybe::next::method($c);
 462     ... do things after Serializing ...
 463   }
 464
 465 =back
 466
 467 =head1 A MILD WARNING
 468
 469 I have code in production using L<Catalyst::Controller::REST>.  That said,
 470 it is still under development, and it's possible that things may change
 471 between releases.  I promise to not break things unneccesarily. :)
 472
 473 =head1 SEE ALSO
 474
 475 L<Catalyst::Action::REST>, L<Catalyst::Action::Serialize>,
 476 L<Catalyst::Action::Deserialize>
 477
 478 For help with REST in general:
 479
 480 The HTTP 1.1 Spec is required reading. http://www.w3.org/Protocols/rfc2616/rfc2616.txt
 481
 482 Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
 483
 484 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
 485
 486 =head1 AUTHOR
 487
 488 Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
 489
 490 Marchex, Inc. paid me while I developed this module.  (http://www.marchex.com)
 491
 492 =head1 MAINTAINER
 493
 494 J. Shirley <jshirley@cpan.org>
 495
 496 =head1 LICENSE
 497
 498 You may distribute this code under the same terms as Perl itself.
 499
 500 =cut
 501
 502 1;