lib/Catalyst/Controller/REST.pm

   1 package Catalyst::Controller::REST;
   2 use Moose;
   3 use namespace::autoclean;
   4
   5 our $VERSION = '0.94';
   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     use Moose;
  16     use namespace::autoclean;
  17
  18     BEGIN { extends 'Catalyst::Controller::REST' }
  19
  20     sub thing : Local : ActionClass('REST') { }
  21
  22     # Answer GET requests to "thing"
  23     sub thing_GET {
  24        my ( $self, $c ) = @_;
  25
  26        # Return a 200 OK, with the data in entity
  27        # serialized in the body
  28        $self->status_ok(
  29             $c,
  30             entity => {
  31                 some => 'data',
  32                 foo  => 'is real bar-y',
  33             },
  34        );
  35     }
  36
  37     # Answer PUT requests to "thing"
  38     sub thing_PUT {
  39         my ( $self, $c ) = @_;
  40
  41         $radiohead = $c->req->data->{radiohead};
  42
  43         $self->status_created(
  44             $c,
  45             location => $c->req->uri->as_string,
  46             entity => {
  47                 radiohead => $radiohead,
  48             }
  49         );
  50     }
  51
  52 =head1 DESCRIPTION
  53
  54 Catalyst::Controller::REST implements a mechanism for building
  55 RESTful services in Catalyst.  It does this by extending the
  56 normal Catalyst dispatch mechanism to allow for different
  57 subroutines to be called based on the HTTP Method requested,
  58 while also transparently handling all the serialization/deserialization for
  59 you.
  60
  61 This is probably best served by an example.  In the above
  62 controller, we have declared a Local Catalyst action on
  63 "sub thing", and have used the ActionClass('REST').
  64
  65 Below, we have declared "thing_GET" and "thing_PUT".  Any
  66 GET requests to thing will be dispatched to "thing_GET",
  67 while any PUT requests will be dispatched to "thing_PUT".
  68
  69 Any unimplemented HTTP methods will be met with a "405 Method Not Allowed"
  70 response, automatically containing the proper list of available methods.  You
  71 can override this behavior through implementing a custom
  72 C<thing_not_implemented> method.
  73
  74 If you do not provide an OPTIONS handler, we will respond to any OPTIONS
  75 requests with a "200 OK", populating the Allowed header automatically.
  76
  77 Any data included in C<< $c->stash->{'rest'} >> will be serialized for you.
  78 The serialization format will be selected based on the content-type
  79 of the incoming request.  It is probably easier to use the L<STATUS HELPERS>,
  80 which are described below.
  81
  82 "The HTTP POST, PUT, and OPTIONS methods will all automatically
  83 L<deserialize|Catalyst::Action::Deserialize> the contents of
  84 C<< $c->request->body >> into the C<< $c->request->data >> hashref", based on
  85 the request's C<Content-type> header. A list of understood serialization
  86 formats is L<below|/AVAILABLE SERIALIZERS>.
  87
  88 If we do not have (or cannot run) a serializer for a given content-type, a 415
  89 "Unsupported Media Type" error is generated.
  90
  91 To make your Controller RESTful, simply have it
  92
  93   BEGIN { extends 'Catalyst::Controller::REST' }
  94
  95 =head1 CONFIGURATION
  96
  97 See L<Catalyst::Action::Serialize/CONFIGURATION>. Note that the C<serialize>
  98 key has been deprecated.
  99
 100 =head1 SERIALIZATION
 101
 102 Catalyst::Controller::REST will automatically serialize your
 103 responses, and deserialize any POST, PUT or OPTIONS requests. It evaluates
 104 which serializer to use by mapping a content-type to a Serialization module.
 105 We select the content-type based on:
 106
 107 =over
 108
 109 =item B<The Content-Type Header>
 110
 111 If the incoming HTTP Request had a Content-Type header set, we will use it.
 112
 113 =item B<The content-type Query Parameter>
 114
 115 If this is a GET request, you can supply a content-type query parameter.
 116
 117 =item B<Evaluating the Accept Header>
 118
 119 Finally, if the client provided an Accept header, we will evaluate
 120 it and use the best-ranked choice.
 121
 122 =back
 123
 124 =head1 AVAILABLE SERIALIZERS
 125
 126 A given serialization mechanism is only available if you have the underlying
 127 modules installed.  For example, you can't use XML::Simple if it's not already
 128 installed.
 129
 130 In addition, each serializer has its quirks in terms of what sorts of data
 131 structures it will properly handle.  L<Catalyst::Controller::REST> makes
 132 no attempt to save you from yourself in this regard. :)
 133
 134 =over 2
 135
 136 =item * C<text/x-yaml> => C<YAML::Syck>
 137
 138 Returns YAML generated by L<YAML::Syck>.
 139
 140 =item * C<text/html> => C<YAML::HTML>
 141
 142 This uses L<YAML::Syck> and L<URI::Find> to generate YAML with all URLs turned
 143 to hyperlinks.  Only usable for Serialization.
 144
 145 =item * C<application/json> => C<JSON>
 146
 147 Uses L<JSON> to generate JSON output.  It is strongly advised to also have
 148 L<JSON::XS> installed.  The C<text/x-json> content type is supported but is
 149 deprecated and you will receive warnings in your log.
 150
 151 You can also add a hash in your controller config to pass options to the json object.
 152 For instance, to relax permissions when deserializing input, add:
 153   __PACKAGE__->config(
 154     json_options => { relaxed => 1 }
 155   )
 156
 157 =item * C<text/javascript> => C<JSONP>
 158
 159 If a callback=? parameter is passed, this returns javascript in the form of: $callback($serializedJSON);
 160
 161 Note - this is disabled by default as it can be a security risk if you are unaware.
 162
 163 The usual MIME types for this serialization format are: 'text/javascript', 'application/x-javascript',
 164 'application/javascript'.
 165
 166 =item * C<text/x-data-dumper> => C<Data::Serializer>
 167
 168 Uses the L<Data::Serializer> module to generate L<Data::Dumper> output.
 169
 170 =item * C<text/x-data-denter> => C<Data::Serializer>
 171
 172 Uses the L<Data::Serializer> module to generate L<Data::Denter> output.
 173
 174 =item * C<text/x-data-taxi> => C<Data::Serializer>
 175
 176 Uses the L<Data::Serializer> module to generate L<Data::Taxi> output.
 177
 178 =item * C<application/x-storable> => C<Data::Serializer>
 179
 180 Uses the L<Data::Serializer> module to generate L<Storable> output.
 181
 182 =item * C<application/x-freezethaw> => C<Data::Serializer>
 183
 184 Uses the L<Data::Serializer> module to generate L<FreezeThaw> output.
 185
 186 =item * C<text/x-config-general> => C<Data::Serializer>
 187
 188 Uses the L<Data::Serializer> module to generate L<Config::General> output.
 189
 190 =item * C<text/x-php-serialization> => C<Data::Serializer>
 191
 192 Uses the L<Data::Serializer> module to generate L<PHP::Serialization> output.
 193
 194 =item * C<text/xml> => C<XML::Simple>
 195
 196 Uses L<XML::Simple> to generate XML output.  This is probably not suitable
 197 for any real heavy XML work. Due to L<XML::Simple>s requirement that the data
 198 you serialize be a HASHREF, we transform outgoing data to be in the form of:
 199
 200   { data => $yourdata }
 201
 202 =item * L<View>
 203
 204 Uses a regular Catalyst view.  For example, if you wanted to have your
 205 C<text/html> and C<text/xml> views rendered by TT, set:
 206
 207   __PACKAGE__->config(
 208       map => {
 209           'text/html' => [ 'View', 'TT' ],
 210           'text/xml'  => [ 'View', 'XML' ],
 211       }
 212   );
 213
 214 Your views should have a C<process> method like this:
 215
 216   sub process {
 217       my ( $self, $c, $stash_key ) = @_;
 218
 219       my $output;
 220       eval {
 221           $output = $self->serialize( $c->stash->{$stash_key} );
 222       };
 223       return $@ if $@;
 224
 225       $c->response->body( $output );
 226       return 1;  # important
 227   }
 228
 229   sub serialize {
 230       my ( $self, $data ) = @_;
 231
 232       my $serialized = ... process $data here ...
 233
 234       return $serialized;
 235   }
 236
 237 =item * Callback
 238
 239 For infinite flexibility, you can provide a callback for the
 240 deserialization/serialization steps.
 241
 242   __PACKAGE__->config(
 243       map => {
 244           'text/xml'  => [ 'Callback', { deserialize => \&parse_xml, serialize => \&render_xml } ],
 245       }
 246   );
 247
 248 The C<deserialize> callback is passed a string that is the body of the
 249 request and is expected to return a scalar value that results from
 250 the deserialization.  The C<serialize> callback is passed the data
 251 structure that needs to be serialized and must return a string suitable
 252 for returning in the HTTP response.  In addition to receiving the scalar
 253 to act on, both callbacks are passed the controller object and the context
 254 (i.e. C<$c>) as the second and third arguments.
 255
 256 =back
 257
 258 By default, L<Catalyst::Controller::REST> will return a
 259 C<415 Unsupported Media Type> response if an attempt to use an unsupported
 260 content-type is made.  You can ensure that something is always returned by
 261 setting the C<default> config option:
 262
 263   __PACKAGE__->config(default => 'text/x-yaml');
 264
 265 would make it always fall back to the serializer plugin defined for
 266 C<text/x-yaml>.
 267
 268 =head1 CUSTOM SERIALIZERS
 269
 270 Implementing new Serialization formats is easy!  Contributions
 271 are most welcome!  If you would like to implement a custom serializer,
 272 you should create two new modules in the L<Catalyst::Action::Serialize>
 273 and L<Catalyst::Action::Deserialize> namespace.  Then assign your new
 274 class to the content-type's you want, and you're done.
 275
 276 See L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>
 277 for more information.
 278
 279 =head1 STATUS HELPERS
 280
 281 Since so much of REST is in using HTTP, we provide these Status Helpers.
 282 Using them will ensure that you are responding with the proper codes,
 283 headers, and entities.
 284
 285 These helpers try and conform to the HTTP 1.1 Specification.  You can
 286 refer to it at: L<http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
 287 These routines are all implemented as regular subroutines, and as
 288 such require you pass the current context ($c) as the first argument.
 289
 290 =over
 291
 292 =cut
 293
 294 BEGIN { extends 'Catalyst::Controller' }
 295 use Params::Validate qw(SCALAR OBJECT);
 296
 297 __PACKAGE__->mk_accessors(qw(serialize));
 298
 299 __PACKAGE__->config(
 300     'stash_key' => 'rest',
 301     'map'       => {
 302         'text/html'          => 'YAML::HTML',
 303         'text/xml'           => 'XML::Simple',
 304         'text/x-yaml'        => 'YAML',
 305         'application/json'   => 'JSON',
 306         'text/x-json'        => 'JSON',
 307         'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
 308         'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
 309         'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
 310         'application/x-storable'   => [ 'Data::Serializer', 'Storable' ],
 311         'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
 312         'text/x-config-general'    => [ 'Data::Serializer', 'Config::General' ],
 313         'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
 314     },
 315 );
 316
 317 sub begin : ActionClass('Deserialize') { }
 318
 319 sub end : ActionClass('Serialize') { }
 320
 321 =item status_ok
 322
 323 Returns a "200 OK" response.  Takes an "entity" to serialize.
 324
 325 Example:
 326
 327   $self->status_ok(
 328     $c,
 329     entity => {
 330         radiohead => "Is a good band!",
 331     }
 332   );
 333
 334 =cut
 335
 336 sub status_ok {
 337     my $self = shift;
 338     my $c    = shift;
 339     my %p    = Params::Validate::validate( @_, { entity => 1, }, );
 340
 341     $c->response->status(200);
 342     $self->_set_entity( $c, $p{'entity'} );
 343     return 1;
 344 }
 345
 346 =item status_created
 347
 348 Returns a "201 CREATED" response.  Takes an "entity" to serialize,
 349 and a "location" where the created object can be found.
 350
 351 Example:
 352
 353   $self->status_created(
 354     $c,
 355     location => $c->req->uri->as_string,
 356     entity => {
 357         radiohead => "Is a good band!",
 358     }
 359   );
 360
 361 In the above example, we use the requested URI as our location.
 362 This is probably what you want for most PUT requests.
 363
 364 =cut
 365
 366 sub status_created {
 367     my $self = shift;
 368     my $c    = shift;
 369     my %p    = Params::Validate::validate(
 370         @_,
 371         {
 372             location => { type     => SCALAR | OBJECT },
 373             entity   => { optional => 1 },
 374         },
 375     );
 376
 377     my $location;
 378     if ( ref( $p{'location'} ) ) {
 379         $location = $p{'location'}->as_string;
 380     } else {
 381         $location = $p{'location'};
 382     }
 383     $c->response->status(201);
 384     $c->response->header( 'Location' => $location );
 385     $self->_set_entity( $c, $p{'entity'} );
 386     return 1;
 387 }
 388
 389 =item status_accepted
 390
 391 Returns a "202 ACCEPTED" response.  Takes an "entity" to serialize.
 392
 393 Example:
 394
 395   $self->status_accepted(
 396     $c,
 397     entity => {
 398         status => "queued",
 399     }
 400   );
 401
 402 =cut
 403
 404 sub status_accepted {
 405     my $self = shift;
 406     my $c    = shift;
 407     my %p    = Params::Validate::validate( @_, { entity => 1, }, );
 408
 409     $c->response->status(202);
 410     $self->_set_entity( $c, $p{'entity'} );
 411     return 1;
 412 }
 413
 414 =item status_no_content
 415
 416 Returns a "204 NO CONTENT" response.
 417
 418 =cut
 419
 420 sub status_no_content {
 421     my $self = shift;
 422     my $c    = shift;
 423     $c->response->status(204);
 424     $self->_set_entity( $c, undef );
 425     return 1;
 426 }
 427
 428 =item status_multiple_choices
 429
 430 Returns a "300 MULTIPLE CHOICES" response. Takes an "entity" to serialize, which should
 431 provide list of possible locations. Also takes optional "location" for preferred choice.
 432
 433 =cut
 434
 435 sub status_multiple_choices {
 436     my $self = shift;
 437     my $c    = shift;
 438     my %p    = Params::Validate::validate(
 439         @_,
 440         {
 441             entity => 1,
 442             location => { type     => SCALAR | OBJECT, optional => 1 },
 443         },
 444     );
 445
 446     my $location;
 447     if ( ref( $p{'location'} ) ) {
 448         $location = $p{'location'}->as_string;
 449     } else {
 450         $location = $p{'location'};
 451     }
 452     $c->response->status(300);
 453     $c->response->header( 'Location' => $location ) if exists $p{'location'};
 454     $self->_set_entity( $c, $p{'entity'} );
 455     return 1;
 456 }
 457
 458 =item status_found
 459
 460 Returns a "302 FOUND" response. Takes an "entity" to serialize.
 461 Also takes optional "location" for preferred choice.
 462
 463 =cut
 464
 465 sub status_found {
 466     my $self = shift;
 467     my $c    = shift;
 468     my %p    = Params::Validate::validate(
 469         @_,
 470         {
 471             entity => 1,
 472             location => { type     => SCALAR | OBJECT, optional => 1 },
 473         },
 474     );
 475
 476     my $location;
 477     if ( ref( $p{'location'} ) ) {
 478         $location = $p{'location'}->as_string;
 479     } else {
 480         $location = $p{'location'};
 481     }
 482     $c->response->status(302);
 483     $c->response->header( 'Location' => $location ) if exists $p{'location'};
 484     $self->_set_entity( $c, $p{'entity'} );
 485     return 1;
 486 }
 487
 488 =item status_bad_request
 489
 490 Returns a "400 BAD REQUEST" response.  Takes a "message" argument
 491 as a scalar, which will become the value of "error" in the serialized
 492 response.
 493
 494 Example:
 495
 496   $self->status_bad_request(
 497     $c,
 498     message => "Cannot do what you have asked!",
 499   );
 500
 501 =cut
 502
 503 sub status_bad_request {
 504     my $self = shift;
 505     my $c    = shift;
 506     my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
 507
 508     $c->response->status(400);
 509     $c->log->debug( "Status Bad Request: " . $p{'message'} ) if $c->debug;
 510     $self->_set_entity( $c, { error => $p{'message'} } );
 511     return 1;
 512 }
 513
 514 =item status_forbidden
 515
 516 Returns a "403 FORBIDDEN" response.  Takes a "message" argument
 517 as a scalar, which will become the value of "error" in the serialized
 518 response.
 519
 520 Example:
 521
 522   $self->status_forbidden(
 523     $c,
 524     message => "access denied",
 525   );
 526
 527 =cut
 528
 529 sub status_forbidden {
 530     my $self = shift;
 531     my $c    = shift;
 532     my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
 533
 534     $c->response->status(403);
 535     $c->log->debug( "Status Forbidden: " . $p{'message'} ) if $c->debug;
 536     $self->_set_entity( $c, { error => $p{'message'} } );
 537     return 1;
 538 }
 539
 540 =item status_not_found
 541
 542 Returns a "404 NOT FOUND" response.  Takes a "message" argument
 543 as a scalar, which will become the value of "error" in the serialized
 544 response.
 545
 546 Example:
 547
 548   $self->status_not_found(
 549     $c,
 550     message => "Cannot find what you were looking for!",
 551   );
 552
 553 =cut
 554
 555 sub status_not_found {
 556     my $self = shift;
 557     my $c    = shift;
 558     my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
 559
 560     $c->response->status(404);
 561     $c->log->debug( "Status Not Found: " . $p{'message'} ) if $c->debug;
 562     $self->_set_entity( $c, { error => $p{'message'} } );
 563     return 1;
 564 }
 565
 566 =item gone
 567
 568 Returns a "41O GONE" response.  Takes a "message" argument as a scalar,
 569 which will become the value of "error" in the serialized response.
 570
 571 Example:
 572
 573   $self->status_gone(
 574     $c,
 575     message => "The document have been deleted by foo",
 576   );
 577
 578 =cut
 579
 580 sub status_gone {
 581     my $self = shift;
 582     my $c    = shift;
 583     my %p    = Params::Validate::validate( @_, { message => { type => SCALAR }, }, );
 584
 585     $c->response->status(410);
 586     $c->log->debug( "Status Gone " . $p{'message'} ) if $c->debug;
 587     $self->_set_entity( $c, { error => $p{'message'} } );
 588     return 1;
 589 }
 590
 591 sub _set_entity {
 592     my $self   = shift;
 593     my $c      = shift;
 594     my $entity = shift;
 595     if ( defined($entity) ) {
 596         $c->stash->{ $self->{'stash_key'} } = $entity;
 597     }
 598     return 1;
 599 }
 600
 601 =back
 602
 603 =head1 MANUAL RESPONSES
 604
 605 If you want to construct your responses yourself, all you need to
 606 do is put the object you want serialized in $c->stash->{'rest'}.
 607
 608 =head1 IMPLEMENTATION DETAILS
 609
 610 This Controller ties together L<Catalyst::Action::REST>,
 611 L<Catalyst::Action::Serialize> and L<Catalyst::Action::Deserialize>.  It should be suitable for most applications.  You should be aware that it:
 612
 613 =over 4
 614
 615 =item Configures the Serialization Actions
 616
 617 This class provides a default configuration for Serialization.  It is currently:
 618
 619   __PACKAGE__->config(
 620       'stash_key' => 'rest',
 621       'map'       => {
 622          'text/html'          => 'YAML::HTML',
 623          'text/xml'           => 'XML::Simple',
 624          'text/x-yaml'        => 'YAML',
 625          'application/json'   => 'JSON',
 626          'text/x-json'        => 'JSON',
 627          'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
 628          'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
 629          'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
 630          'application/x-storable'   => [ 'Data::Serializer', 'Storable' ],
 631          'application/x-freezethaw' => [ 'Data::Serializer', 'FreezeThaw' ],
 632          'text/x-config-general'    => [ 'Data::Serializer', 'Config::General' ],
 633          'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
 634       },
 635   );
 636
 637 You can read the full set of options for this configuration block in
 638 L<Catalyst::Action::Serialize>.
 639
 640 =item Sets a C<begin> and C<end> method for you
 641
 642 The C<begin> method uses L<Catalyst::Action::Deserialize>.  The C<end>
 643 method uses L<Catalyst::Action::Serialize>.  If you want to override
 644 either behavior, simply implement your own C<begin> and C<end> actions
 645 and forward to another action with the Serialize and/or Deserialize
 646 action classes:
 647
 648   package Foo::Controller::Monkey;
 649   use Moose;
 650   use namespace::autoclean;
 651
 652   BEGIN { extends 'Catalyst::Controller::REST' }
 653
 654   sub begin : Private {
 655     my ($self, $c) = @_;
 656     ... do things before Deserializing ...
 657     $c->forward('deserialize');
 658     ... do things after Deserializing ...
 659   }
 660
 661   sub deserialize : ActionClass('Deserialize') {}
 662
 663   sub end :Private {
 664     my ($self, $c) = @_;
 665     ... do things before Serializing ...
 666     $c->forward('serialize');
 667     ... do things after Serializing ...
 668   }
 669
 670   sub serialize : ActionClass('Serialize') {}
 671
 672 If you need to deserialize multipart requests (i.e. REST data in
 673 one part and file uploads in others) you can do so by using the
 674 L<Catalyst::Action::DeserializeMultiPart> action class.
 675
 676 =back
 677
 678 =head1 A MILD WARNING
 679
 680 I have code in production using L<Catalyst::Controller::REST>.  That said,
 681 it is still under development, and it's possible that things may change
 682 between releases.  I promise to not break things unnecessarily. :)
 683
 684 =head1 SEE ALSO
 685
 686 L<Catalyst::Action::REST>, L<Catalyst::Action::Serialize>,
 687 L<Catalyst::Action::Deserialize>
 688
 689 For help with REST in general:
 690
 691 The HTTP 1.1 Spec is required reading. http://www.w3.org/Protocols/rfc2616/rfc2616.txt
 692
 693 Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
 694
 695 The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
 696
 697 =head1 AUTHORS
 698
 699 See L<Catalyst::Action::REST> for authors.
 700
 701 =head1 LICENSE
 702
 703 You may distribute this code under the same terms as Perl itself.
 704
 705 =cut
 706
 707 __PACKAGE__->meta->make_immutable;
 708
 709 1;