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.
  40
  41     It is likely that you really want to look at Catalyst::Controller::REST,
  42     which brings this class together with automatic Serialization of
  43     requests and responses.
  44
  45     When you use this module, it adds the Catalyst::TraitFor::Request::REST
  46     role to your request class.
  47
  48 METHODS
  49     dispatch
  50         This method overrides the default dispatch mechanism to the
  51         re-dispatching mechanism described above.
  52
  53 SEE ALSO
  54     You likely want to look at Catalyst::Controller::REST, which implements
  55     a sensible set of defaults for a controller doing REST.
  56
  57     This class automatically adds the Catalyst::TraitFor::Request::REST role
  58     to your request class. If you're writing a web application which
  59     provides RESTful responses and still needs to accommodate web browsers,
  60     you may prefer to use Catalyst::TraitFor::Request::REST::ForBrowsers
  61     instead.
  62
  63     Catalyst::Action::Serialize, Catalyst::Action::Deserialize
  64
  65 TROUBLESHOOTING
  66     Q: I'm getting a "415 Unsupported Media Type" error. What gives?!
  67         A: Most likely, you haven't set Content-type equal to
  68         "application/json", or one of the accepted return formats. You can
  69         do this by setting it in your query accepted return formats. You can
  70         do this by setting it in your query string thusly:
  71         "?content-type=application%2Fjson (where %2F == / uri escaped)."
  72
  73         NOTE Apache will refuse %2F unless configured otherwise. Make sure
  74         "AllowEncodedSlashes On" is in your httpd.conf file in order for
  75         this to run smoothly.
  76
  77 AUTHOR
  78     Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and
  79     jrockway
  80
  81     Marchex, Inc. paid me while I developed this module.
  82     (<http://www.marchex.com>)
  83
  84 CONTRIBUTORS
  85     Tomas Doran (t0m) <bobtfish@bobtfish.net>
  86
  87     John Goulah
  88
  89     Christopher Laco
  90
  91     Daisuke Maki <daisuke@endeworks.jp>
  92
  93     Hans Dieter Pearcey
  94
  95     Dave Rolsky <autarch@urth.org>
  96
  97     Luke Saunders
  98
  99     Arthur Axel "fREW" Schmidt <frioux@gmail.com>
 100
 101     J. Shirley <jshirley@gmail.com>
 102
 103 COPYRIGHT
 104     Copyright the above named AUTHOR and CONTRIBUTORS
 105
 106 LICENSE
 107     You may distribute this code under the same terms as Perl itself.
 108