README

   1 NAME
   2     Catalyst::Action::REST - Automated REST Method Dispatching
   3
   4 SYNOPSIS
   5         sub foo :Local :ActionClass('REST') {
   6           ... do setup for HTTP method specific handlers ...
   7         }
   8
   9         sub foo_GET {
  10           ... do something for GET requests ...
  11         }
  12
  13         # alternatively use an Action
  14         sub foo_PUT : Action {
  15           ... do something for PUT requests ...
  16         }
  17
  18 DESCRIPTION
  19     This Action handles doing automatic method dispatching for REST
  20     requests. It takes a normal Catalyst action, and changes the dispatch to
  21     append an underscore and method name. First it will try dispatching to
  22     an action with the generated name, and failing that it will try to
  23     dispatch to a regular method.
  24
  25     For example, in the synopsis above, calling GET on "/foo" would result
  26     in the foo_GET method being dispatched.
  27
  28     If a method is requested that is not implemented, this action will
  29     return a status 405 (Method Not Found). It will populate the "Allow"
  30     header with the list of implemented request methods. You can override
  31     this behavior by implementing a custom 405 handler like so:
  32
  33        sub foo_not_implemented {
  34           ... handle not implemented methods ...
  35        }
  36
  37     If you do not provide an _OPTIONS subroutine, we will automatically
  38     respond with a 200 OK. The "Allow" header will be populated with the
  39     list of implemented request methods. If you do not provide an _HEAD
  40     either, we will auto dispatch to the _GET one in case it exists.
  41
  42     It is likely that you really want to look at Catalyst::Controller::REST,
  43     which brings this class together with automatic Serialization of
  44     requests and responses.
  45
  46     When you use this module, it adds the Catalyst::TraitFor::Request::REST
  47     role to your request class.
  48
  49 METHODS
  50     dispatch
  51         This method overrides the default dispatch mechanism to the
  52         re-dispatching mechanism described above.
  53
  54 SEE ALSO
  55     You likely want to look at Catalyst::Controller::REST, which implements
  56     a sensible set of defaults for a controller doing REST.
  57
  58     This class automatically adds the Catalyst::TraitFor::Request::REST role
  59     to your request class. If you're writing a web application which
  60     provides RESTful responses and still needs to accommodate web browsers,
  61     you may prefer to use Catalyst::TraitFor::Request::REST::ForBrowsers
  62     instead.
  63
  64     Catalyst::Action::Serialize, Catalyst::Action::Deserialize
  65
  66 TROUBLESHOOTING
  67     Q: I'm getting a "415 Unsupported Media Type" error. What gives?!
  68         A: Most likely, you haven't set Content-type equal to
  69         "application/json", or one of the accepted return formats. You can
  70         do this by setting it in your query accepted return formats. You can
  71         do this by setting it in your query string thusly:
  72         "?content-type=application%2Fjson (where %2F == / uri escaped)."
  73
  74         NOTE Apache will refuse %2F unless configured otherwise. Make sure
  75         "AllowEncodedSlashes On" is in your httpd.conf file in order for
  76         this to run smoothly.
  77
  78 AUTHOR
  79     Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and
  80     jrockway
  81
  82     Marchex, Inc. paid me while I developed this module.
  83     (<http://www.marchex.com>)
  84
  85 CONTRIBUTORS
  86     Tomas Doran (t0m) <bobtfish@bobtfish.net>
  87
  88     John Goulah
  89
  90     Christopher Laco
  91
  92     Daisuke Maki <daisuke@endeworks.jp>
  93
  94     Hans Dieter Pearcey
  95
  96     Brian Phillips <bphillips@cpan.org>
  97
  98     Dave Rolsky <autarch@urth.org>
  99
 100     Luke Saunders
 101
 102     Arthur Axel "fREW" Schmidt <frioux@gmail.com>
 103
 104     J. Shirley <jshirley@gmail.com>
 105
 106     Gavin Henry <ghenry@surevoip.co.uk>
 107
 108     Gerv http://www.gerv.net/
 109
 110     Colin Newell <colin@opusvl.com>
 111
 112     Wallace Reis <wreis@cpan.org>
 113
 114 COPYRIGHT
 115     Copyright (c) 2006-2012 the above named AUTHOR and CONTRIBUTORS
 116
 117 LICENSE
 118     You may distribute this code under the same terms as Perl itself.
 119