lib/Catalyst/Controller/REST.pm

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