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_no_content
 336
 337 Returns a "204 NO CONTENT" response.
 338
 339 =cut
 340
 341 sub status_no_content {
 342     my $self = shift;
 343     my $c    = shift;
 344     $c->response->status(204);
 345     $self->_set_entity( $c, undef );
 346     return 1.;
 347 }
 348
 349 =item status_bad_request
 350
 351 Returns a "400 BAD REQUEST" response.  Takes a "message" argument
 352 as a scalar, which will become the value of "error" in the serialized
 353 response.
 354
 355 Example:
 356
 357   $self->status_bad_request(
 358     $c,
 359     message => "Cannot do what you have asked!",
 360   );
 361
 362 =cut
 363
 364 sub status_bad_request {
 365     my $self = shift;
 366     my $c    = shift;
 367     my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
 368
 369     $c->response->status(400);
 370     $c->log->debug( "Status Bad Request: " . $p{'message'} ) if $c->debug;
 371     $self->_set_entity( $c, { error => $p{'message'} } );
 372     return 1;
 373 }
 374
 375 =item status_not_found
 376
 377 Returns a "404 NOT FOUND" response.  Takes a "message" argument
 378 as a scalar, which will become the value of "error" in the serialized
 379 response.
 380
 381 Example:
 382
 383   $self->status_not_found(
 384     $c,
 385     message => "Cannot find what you were looking for!",
 386   );
 387
 388 =cut
 389
 390 sub status_not_found {
 391     my $self = shift;
 392     my $c    = shift;
 393     my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
 394
 395     $c->response->status(404);
 396     $c->log->debug( "Status Not Found: " . $p{'message'} ) if $c->debug;
 397     $self->_set_entity( $c, { error => $p{'message'} } );
 398     return 1;
 399 }
 400
 401 =item gone
 402
 403 Returns a "41O GONE" response.  Takes a "message" argument as a scalar,
 404 which will become the value of "error" in the serialized response.
 405
 406 Example:
 407
 408   $self->status_gone(
 409     $c,
 410     message => "The document have been deleted by foo",
 411   );
 412
 413 =cut
 414
 415 sub status_gone {
 416     my $self = shift;
 417     my $c    = shift;
 418     my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
 419
 420     $c->response->status(410);
 421     $c->log->debug( "Status Gone " . $p{'message'} ) if $c->debug;
 422     $self->_set_entity( $c, { error => $p{'message'} } );
 423     return 1;
 424 }
 425
 426 sub _set_entity {
 427     my $self   = shift;
 428     my $c      = shift;
 429     my $entity = shift;
 430     if ( defined($entity) ) {
 431         $c->stash->{ $self->{'stash_key'} } = $entity;
 432     }
 433     return 1;
 434 }
 435
 436 =back
 437
 438 =head1 MANUAL RESPONSES
 439
 440 If you want to construct your responses yourself, all you need to
 441 do is put the object you want serialized in $c->stash->{'rest'}.
 442
 443 =head1 IMPLEMENTATION DETAILS
 444
 445 This Controller ties together L<Catalyst::Action::REST>,
 446 L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>.  It should be suitable for most applications.  You should be aware that it:
 447
 448 =over 4
 449
 450 =item Configures the Serialization Actions
 451
 452 This class provides a default configuration for Serialization.  It is currently:
 453
 454   __PACKAGE__->config(
 455       serialize => {
 456          'stash_key' => 'rest',
 457          'map'       => {
 458             'text/html'          => 'YAML::HTML',
 459             'text/xml'           => 'XML::Simple',
 460             'text/x-yaml'        => 'YAML',
 461             'application/json'   => 'JSON',
 462             'text/x-json'        => 'JSON',
 463             'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
 464             'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
 465             'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
 466             'application/x-storable'    => [ 'Data::Serializer', 'Storable'
 467 ],
 468             'application/x-freezethaw'  => [ 'Data::Serializer', 'FreezeThaw'
 469 ],
 470             'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ]
 471 ,
 472             'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
 473           },
 474       }
 475   );
 476
 477 You can read the full set of options for this configuration block in
 478 L<Catalyst::Action::Serialize>.
 479
 480 =item Sets a C<begin> and C<end> method for you
 481
 482 The C<begin> method uses L<Catalyst::Action::Deserialize>.  The C<end>
 483 method uses L<Catalyst::Action::Serialize>.  If you want to override
 484 either behavior, simply implement your own C<begin> and C<end> actions
 485 and use MRO::Compat:
 486
 487   my Foo::Controller::Monkey;
 488   use base qw(Catalyst::Controller::REST);
 489
 490   sub begin :Private {
 491     my ($self, $c) = @_;
 492     ... do things before Deserializing ...
 493     $self->maybe::next::method($c);
 494     ... do things after Deserializing ...
 495   }
 496
 497   sub end :Private {
 498     my ($self, $c) = @_;
 499     ... do things before Serializing ...
 500     $self->maybe::next::method($c);
 501     ... do things after Serializing ...
 502   }
 503
 504 =back
 505
 506 =head1 A MILD WARNING
 507
 508 I have code in production using L<Catalyst::Controller::REST>.  That said,
 509 it is still under development, and it's possible that things may change
 510 between releases.  I promise to not break things unneccesarily. :)
 511
 512 =head1 SEE ALSO
 513
 514 L<Catalyst::Action::REST>, L<Catalyst::Action::Serialize>,
 515 L<Catalyst::Action::Deserialize>
 516
 517 For help with REST in general:
 518
 519 The HTTP 1.1 Spec is required reading. http://www.w3.org/Protocols/rfc2616/rfc2616.txt
 520
 521 Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
 522
 523 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
 524
 525 =head1 AUTHOR
 526
 527 Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
 528
 529 Marchex, Inc. paid me while I developed this module.  (http://www.marchex.com)
 530
 531 =head1 MAINTAINER
 532
 533 J. Shirley <jshirley@cpan.org>
 534
 535 =head1 LICENSE
 536
 537 You may distribute this code under the same terms as Perl itself.
 538
 539 =cut
 540
 541 1;