lib/Catalyst/Action/REST.pm

   1 #
   2 # REST.pm
   3 # Created by: Adam Jacob, Marchex, <adam@marchex.com>
   4 # Created on: 10/12/2006 03:00:32 PM PDT
   5 #
   6 # $Id$
   7
   8 package Catalyst::Action::REST;
   9
  10 use strict;
  11 use warnings;
  12
  13 use base 'Catalyst::Action';
  14 use Class::Inspector;
  15 use 5.8.1;
  16
  17 my
  18 $VERSION = '0.1';
  19
  20 =head1 NAME
  21
  22 Catalyst::Action::REST - Automated REST Method Dispatching
  23
  24 =head1 SYNOPSIS
  25
  26     sub foo :Local :ActionClass('REST') {}
  27
  28     sub foo_GET {
  29       ... do something for GET requests ...
  30     }
  31
  32     sub foo_PUT {
  33       ... do somethign for PUT requests ...
  34     }
  35
  36 =head1 DESCRIPTION
  37
  38 This Action handles doing automatic method dispatching for REST requests.  It
  39 takes a normal Catalyst action, and changes the dispatch to append an
  40 underscore and method name.
  41
  42 For example, in the synopsis above, calling GET on "/foo" would result in
  43 the foo_GET method being dispatched.
  44
  45 If a method is requested that is not implemented, this action will
  46 return a status 405 (Method Not Found).  It will populate the "Allow" header
  47 with the list of implemented request methods.
  48
  49 =head1 METHODS
  50
  51 =over 4
  52
  53 =item dispatch
  54
  55 This method overrides the default dispatch mechanism to the re-dispatching
  56 mechanism described above.
  57
  58 =cut
  59 sub dispatch {
  60     my $self = shift;
  61     my $c = shift;
  62
  63     my $controller = $self->class;
  64     my $method     = $self->name . "_" . uc( $c->request->method );
  65     if ( $controller->can($method) ) {
  66         return $controller->$method($c, @{$c->req->args});
  67     } else {
  68         $self->_return_405($c);
  69         return $c->execute( $self->class, $self, @{$c->req->args} );
  70     }
  71 }
  72
  73 sub _return_405 {
  74     my ( $self, $c ) = @_;
  75
  76     my $controller = $self->class;
  77     my $methods    = Class::Inspector->methods($controller);
  78     my @allowed;
  79     foreach my $method ( @{$methods} ) {
  80         my $name = $self->name;
  81         if ( $method =~ /^$name\_(.+)$/ ) {
  82             push( @allowed, $1 );
  83         }
  84     }
  85     $c->response->content_type('text/plain');
  86     $c->response->status(405);
  87     $c->response->header( 'Allow' => \@allowed );
  88     $c->response->body( "Method "
  89           . $c->request->method
  90           . " not implemented for "
  91           . $c->uri_for( $self->reverse ) );
  92 }
  93
  94 1;
  95
  96 =back
  97
  98 =head1 SEE ALSO
  99
 100 You likely want to look at L<Catalyst::Controller::REST>, which implements
 101 a sensible set of defaults for a controller doing REST.
 102
 103 L<Catalyst::Action::Serialize>, L<Catalyst::Action::Deserialize>
 104
 105 =head1 AUTHOR
 106
 107 Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
 108
 109 =head1 LICENSE
 110
 111 You may distribute this code under the same terms as Perl itself.
 112
 113 =cut