README

   1 NAME
   2     Catalyst::Controller::REST - A RESTful controller
   3
   4 SYNOPSIS
   5         package Foo::Controller::Bar;
   6
   7         use base 'Catalyst::Controller::REST';
   8
   9         sub thing : Local : ActionClass('REST') { }
  10
  11         # Answer GET requests to "thing"
  12         sub thing_GET {
  13            my ( $self, $c ) = @_;
  14
  15            # Return a 200 OK, with the data in entity
  16            # serialized in the body
  17            $self->status_ok(
  18                 $c,
  19                 entity => {
  20                     some => 'data',
  21                     foo  => 'is real bar-y',
  22                 },
  23            );
  24         }
  25
  26         # Answer PUT requests to "thing"
  27         sub thing_PUT {
  28           .. some action ..
  29         }
  30
  31 DESCRIPTION
  32     Catalyst::Controller::REST implements a mechanism for building RESTful
  33     services in Catalyst. It does this by extending the normal Catalyst
  34     dispatch mechanism to allow for different subroutines to be called based
  35     on the HTTP Method requested, while also transparently handling all the
  36     serialization/deserialization for you.
  37
  38     This is probably best served by an example. In the above controller, we
  39     have declared a Local Catalyst action on "sub thing", and have used the
  40     ActionClass('REST').
  41
  42     Below, we have declared "thing_GET" and "thing_PUT". Any GET requests to
  43     thing will be dispatched to "thing_GET", while any PUT requests will be
  44     dispatched to "thing_PUT".
  45
  46     Any unimplemented HTTP METHODS will be met with a "405 Method Not
  47     Allowed" response, automatically containing the proper list of available
  48     methods.
  49
  50     The HTTP POST, PUT, and OPTIONS methods will all automatically
  51     deserialize the contents of $c->request->body based on the requests
  52     content-type header. A list of understood serialization formats is
  53     below.
  54
  55     Also included in this class are several helper methods, which will
  56     automatically handle setting up proper response objects for you.
  57
  58     To make your Controller RESTful, simply have it
  59
  60       use base 'Catalyst::Controller::REST';
  61
  62 SERIALIZATION
  63     Catalyst::Controller::REST will automatically serialize your responses.
  64     The currently implemented serialization formats are:
  65
  66        text/x-yaml        ->   YAML::Syck
  67        text/x-data-dumper ->   Data::Serializer
  68
  69     By default, Catalyst::Controller::REST will use YAML as the
  70     serialization format.
  71
  72     Implementing new Serialization formats is easy! Contributions are most
  73     welcome! See Catalyst::Action::Serialize and
  74     Catalyst::Action::Deserialize for more information.
  75
  76 STATUS HELPERS
  77     These helpers try and conform to the HTTP 1.1 Specification. You can
  78     refer to it at: http://www.w3.org/Protocols/rfc2616/rfc2616.txt. These
  79     routines are all implemented as regular subroutines, and as such require
  80     you pass the current context ($c) as the first argument.
  81
  82     status_ok
  83         Returns a "200 OK" response. Takes an "entity" to serialize.
  84
  85         Example:
  86
  87           $self->status_ok(
  88             $c,
  89             entity => {
  90                 radiohead => "Is a good band!",
  91             }
  92           );
  93
  94     status_created
  95         Returns a "201 CREATED" response. Takes an "entity" to serialize,
  96         and a "location" where the created object can be found.
  97
  98         Example:
  99
 100           $self->status_created(
 101             $c,
 102             location => $c->req->uri->as_string,
 103             entity => {
 104                 radiohead => "Is a good band!",
 105             }
 106           );
 107
 108         In the above example, we use the requested URI as our location. This
 109         is probably what you want for most PUT requests.
 110
 111     status_accepted
 112         Returns a "202 ACCEPTED" response. Takes an "entity" to serialize.
 113
 114         Example:
 115
 116           $self->status_accepted(
 117             $c,
 118             entity => {
 119                 status => "queued",
 120             }
 121           );
 122
 123     status_bad_request
 124         Returns a "400 BAD REQUEST" response. Takes a "message" argument as
 125         a scalar, which will become the value of "error" in the serialized
 126         response.
 127
 128         Example:
 129
 130           $self->status_bad_request(
 131             $c,
 132             entity => {
 133                 message => "Cannot do what you have asked!",
 134             }
 135           );
 136
 137     status_not_found
 138         Returns a "404 NOT FOUND" response. Takes a "message" argument as a
 139         scalar, which will become the value of "error" in the serialized
 140         response.
 141
 142         Example:
 143
 144           $self->status_not_found(
 145             $c,
 146             entity => {
 147                 message => "Cannot find what you were looking for!",
 148             }
 149           );
 150
 151 MANUAL RESPONSES
 152     If you want to construct your responses yourself, all you need to do is
 153     put the object you want serialized in $c->stash->{'rest'}.
 154
 155 SEE ALSO
 156     Catalyst::Action::REST, Catalyst::Action::Serialize,
 157     Catalyst::Action::Deserialize
 158
 159     For help with REST in general:
 160
 161     The HTTP 1.1 Spec is required reading.
 162     http://www.w3.org/Protocols/rfc2616/rfc2616.txt
 163
 164     Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
 165
 166     The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage
 167
 168 AUTHOR
 169     Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and
 170     jrockway
 171
 172     Marchex, Inc. paid me while I developed this module.
 173     (http://www.marchex.com)
 174
 175 LICENSE
 176     You may distribute this code under the same terms as Perl itself.
 177