local-lib5/man/man3/Catalyst::Controller::REST.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Catalyst::Controller::REST 3"
 127 .TH Catalyst::Controller::REST 3 "2010-05-13" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Catalyst::Controller::REST \- A RESTful controller
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&    package Foo::Controller::Bar;
 138 \&    use Moose;
 139 \&    use namespace::autoclean;
 140 \&
 141 \&    BEGIN { extends \*(AqCatalyst::Controller::REST\*(Aq }
 142 \&
 143 \&    sub thing : Local : ActionClass(\*(AqREST\*(Aq) { }
 144 \&
 145 \&    # Answer GET requests to "thing"
 146 \&    sub thing_GET {
 147 \&       my ( $self, $c ) = @_;
 148 \&
 149 \&       # Return a 200 OK, with the data in entity
 150 \&       # serialized in the body
 151 \&       $self\->status_ok(
 152 \&            $c,
 153 \&            entity => {
 154 \&                some => \*(Aqdata\*(Aq,
 155 \&                foo  => \*(Aqis real bar\-y\*(Aq,
 156 \&            },
 157 \&       );
 158 \&    }
 159 \&
 160 \&    # Answer PUT requests to "thing"
 161 \&    sub thing_PUT {
 162 \&        $radiohead = $req\->data\->{radiohead};
 163 \&
 164 \&        $self\->status_created(
 165 \&            $c,
 166 \&            location => $c\->req\->uri\->as_string,
 167 \&            entity => {
 168 \&                radiohead => $radiohead,
 169 \&            }
 170 \&        );
 171 \&    }
 172 .Ve
 173 .SH "DESCRIPTION"
 174 .IX Header "DESCRIPTION"
 175 Catalyst::Controller::REST implements a mechanism for building
 176 RESTful services in Catalyst.  It does this by extending the
 177 normal Catalyst dispatch mechanism to allow for different
 178 subroutines to be called based on the \s-1HTTP\s0 Method requested,
 179 while also transparently handling all the serialization/deserialization for
 180 you.
 181 .PP
 182 This is probably best served by an example.  In the above
 183 controller, we have declared a Local Catalyst action on
 184 \&\*(L"sub thing\*(R", and have used the ActionClass('\s-1REST\s0').
 185 .PP
 186 Below, we have declared \*(L"thing_GET\*(R" and \*(L"thing_PUT\*(R".  Any
 187 \&\s-1GET\s0 requests to thing will be dispatched to \*(L"thing_GET\*(R",
 188 while any \s-1PUT\s0 requests will be dispatched to \*(L"thing_PUT\*(R".
 189 .PP
 190 Any unimplemented \s-1HTTP\s0 methods will be met with a \*(L"405 Method Not Allowed\*(R"
 191 response, automatically containing the proper list of available methods.  You
 192 can override this behavior through implementing a custom
 193 \&\f(CW\*(C`thing_not_implemented\*(C'\fR method.
 194 .PP
 195 If you do not provide an \s-1OPTIONS\s0 handler, we will respond to any \s-1OPTIONS\s0
 196 requests with a \*(L"200 \s-1OK\s0\*(R", populating the Allowed header automatically.
 197 .PP
 198 Any data included in \f(CW\*(C`$c\->stash\->{\*(Aqrest\*(Aq}\*(C'\fR will be serialized for you.
 199 The serialization format will be selected based on the content-type
 200 of the incoming request.  It is probably easier to use the \*(L"\s-1STATUS\s0 \s-1HELPERS\s0\*(R",
 201 which are described below.
 202 .PP
 203 "The \s-1HTTP\s0 \s-1POST\s0, \s-1PUT\s0, and \s-1OPTIONS\s0 methods will all automatically
 204 deserialize the contents of
 205 \&\f(CW\*(C`$c\->request\->body\*(C'\fR into the \f(CW\*(C`$c\->request\->data\*(C'\fR hashref", based on
 206 the request's \f(CW\*(C`Content\-type\*(C'\fR header. A list of understood serialization
 207 formats is below.
 208 .PP
 209 If we do not have (or cannot run) a serializer for a given content-type, a 415
 210 \&\*(L"Unsupported Media Type\*(R" error is generated.
 211 .PP
 212 To make your Controller RESTful, simply have it
 213 .PP
 214 .Vb 1
 215 \&  BEGIN { extends \*(AqCatalyst::Controller::REST\*(Aq }
 216 .Ve
 217 .SH "CONFIGURATION"
 218 .IX Header "CONFIGURATION"
 219 See \*(L"\s-1CONFIGURATION\s0\*(R" in Catalyst::Action::Serialize. Note that the \f(CW\*(C`serialize\*(C'\fR
 220 key has been deprecated.
 221 .SH "SERIALIZATION"
 222 .IX Header "SERIALIZATION"
 223 Catalyst::Controller::REST will automatically serialize your
 224 responses, and deserialize any \s-1POST\s0, \s-1PUT\s0 or \s-1OPTIONS\s0 requests. It evaluates
 225 which serializer to use by mapping a content-type to a Serialization module.
 226 We select the content-type based on:
 227 .IP "\fBThe Content-Type Header\fR" 4
 228 .IX Item "The Content-Type Header"
 229 If the incoming \s-1HTTP\s0 Request had a Content-Type header set, we will use it.
 230 .IP "\fBThe content-type Query Parameter\fR" 4
 231 .IX Item "The content-type Query Parameter"
 232 If this is a \s-1GET\s0 request, you can supply a content-type query parameter.
 233 .IP "\fBEvaluating the Accept Header\fR" 4
 234 .IX Item "Evaluating the Accept Header"
 235 Finally, if the client provided an Accept header, we will evaluate
 236 it and use the best-ranked choice.
 237 .SH "AVAILABLE SERIALIZERS"
 238 .IX Header "AVAILABLE SERIALIZERS"
 239 A given serialization mechanism is only available if you have the underlying
 240 modules installed.  For example, you can't use XML::Simple if it's not already
 241 installed.
 242 .PP
 243 In addition, each serializer has its quirks in terms of what sorts of data
 244 structures it will properly handle.  Catalyst::Controller::REST makes
 245 no attempt to save you from yourself in this regard. :)
 246 .IP "\(bu" 2
 247 \&\f(CW\*(C`text/x\-yaml\*(C'\fR => \f(CW\*(C`YAML::Syck\*(C'\fR
 248 .Sp
 249 Returns \s-1YAML\s0 generated by YAML::Syck.
 250 .IP "\(bu" 2
 251 \&\f(CW\*(C`text/html\*(C'\fR => \f(CW\*(C`YAML::HTML\*(C'\fR
 252 .Sp
 253 This uses YAML::Syck and URI::Find to generate \s-1YAML\s0 with all URLs turned
 254 to hyperlinks.  Only usable for Serialization.
 255 .IP "\(bu" 2
 256 \&\f(CW\*(C`application/json\*(C'\fR => \f(CW\*(C`JSON\*(C'\fR
 257 .Sp
 258 Uses \s-1JSON\s0 to generate \s-1JSON\s0 output.  It is strongly advised to also have
 259 \&\s-1JSON::XS\s0 installed.  The \f(CW\*(C`text/x\-json\*(C'\fR content type is supported but is
 260 deprecated and you will receive warnings in your log.
 261 .IP "\(bu" 2
 262 \&\f(CW\*(C`text/javascript\*(C'\fR => \f(CW\*(C`JSONP\*(C'\fR
 263 .Sp
 264 If a callback=? parameter is passed, this returns javascript in the form of: \f(CW$callbac\fRk($serializedJSON);
 265 .Sp
 266 Note \- this is disabled by default as it can be a security risk if you are unaware.
 267 .Sp
 268 The usual \s-1MIME\s0 types for this serialization format are: 'text/javascript', 'application/x\-javascript',
 269 \&'application/javascript'.
 270 .IP "\(bu" 2
 271 \&\f(CW\*(C`text/x\-data\-dumper\*(C'\fR => \f(CW\*(C`Data::Serializer\*(C'\fR
 272 .Sp
 273 Uses the Data::Serializer module to generate Data::Dumper output.
 274 .IP "\(bu" 2
 275 \&\f(CW\*(C`text/x\-data\-denter\*(C'\fR => \f(CW\*(C`Data::Serializer\*(C'\fR
 276 .Sp
 277 Uses the Data::Serializer module to generate Data::Denter output.
 278 .IP "\(bu" 2
 279 \&\f(CW\*(C`text/x\-data\-taxi\*(C'\fR => \f(CW\*(C`Data::Serializer\*(C'\fR
 280 .Sp
 281 Uses the Data::Serializer module to generate Data::Taxi output.
 282 .IP "\(bu" 2
 283 \&\f(CW\*(C`application/x\-storable\*(C'\fR => \f(CW\*(C`Data::Serializer\*(C'\fR
 284 .Sp
 285 Uses the Data::Serializer module to generate Storable output.
 286 .IP "\(bu" 2
 287 \&\f(CW\*(C`application/x\-freezethaw\*(C'\fR => \f(CW\*(C`Data::Serializer\*(C'\fR
 288 .Sp
 289 Uses the Data::Serializer module to generate FreezeThaw output.
 290 .IP "\(bu" 2
 291 \&\f(CW\*(C`text/x\-config\-general\*(C'\fR => \f(CW\*(C`Data::Serializer\*(C'\fR
 292 .Sp
 293 Uses the Data::Serializer module to generate Config::General output.
 294 .IP "\(bu" 2
 295 \&\f(CW\*(C`text/x\-php\-serialization\*(C'\fR => \f(CW\*(C`Data::Serializer\*(C'\fR
 296 .Sp
 297 Uses the Data::Serializer module to generate PHP::Serialization output.
 298 .IP "\(bu" 2
 299 \&\f(CW\*(C`text/xml\*(C'\fR => \f(CW\*(C`XML::Simple\*(C'\fR
 300 .Sp
 301 Uses XML::Simple to generate \s-1XML\s0 output.  This is probably not suitable
 302 for any real heavy \s-1XML\s0 work. Due to XML::Simples requirement that the data
 303 you serialize be a \s-1HASHREF\s0, we transform outgoing data to be in the form of:
 304 .Sp
 305 .Vb 1
 306 \&  { data => $yourdata }
 307 .Ve
 308 .IP "\(bu" 2
 309 View
 310 .Sp
 311 Uses a regular Catalyst view.  For example, if you wanted to have your
 312 \&\f(CW\*(C`text/html\*(C'\fR and \f(CW\*(C`text/xml\*(C'\fR views rendered by \s-1TT\s0, set:
 313 .Sp
 314 .Vb 6
 315 \&  _\|_PACKAGE_\|_\->config(
 316 \&      map => {
 317 \&          \*(Aqtext/html\*(Aq => [ \*(AqView\*(Aq, \*(AqTT\*(Aq ],
 318 \&          \*(Aqtext/xml\*(Aq  => [ \*(AqView\*(Aq, \*(AqXML\*(Aq ],
 319 \&      }
 320 \&  );
 321 .Ve
 322 .Sp
 323 Your views should have a \f(CW\*(C`process\*(C'\fR method like this:
 324 .Sp
 325 .Vb 2
 326 \&  sub process {
 327 \&      my ( $self, $c, $stash_key ) = @_;
 328 \&
 329 \&      my $output;
 330 \&      eval {
 331 \&          $output = $self\->serialize( $c\->stash\->{$stash_key} );
 332 \&      };
 333 \&      return $@ if $@;
 334 \&
 335 \&      $c\->response\->body( $output );
 336 \&      return 1;  # important
 337 \&  }
 338 \&
 339 \&  sub serialize {
 340 \&      my ( $self, $data ) = @_;
 341 \&
 342 \&      my $serialized = ... process $data here ...
 343 \&
 344 \&      return $serialized;
 345 \&  }
 346 .Ve
 347 .PP
 348 By default, Catalyst::Controller::REST will return a
 349 \&\f(CW\*(C`415 Unsupported Media Type\*(C'\fR response if an attempt to use an unsupported
 350 content-type is made.  You can ensure that something is always returned by
 351 setting the \f(CW\*(C`default\*(C'\fR config option:
 352 .PP
 353 .Vb 1
 354 \&  _\|_PACKAGE_\|_\->config(default => \*(Aqtext/x\-yaml\*(Aq);
 355 .Ve
 356 .PP
 357 would make it always fall back to the serializer plugin defined for
 358 \&\f(CW\*(C`text/x\-yaml\*(C'\fR.
 359 .SH "CUSTOM SERIALIZERS"
 360 .IX Header "CUSTOM SERIALIZERS"
 361 Implementing new Serialization formats is easy!  Contributions
 362 are most welcome!  If you would like to implement a custom serializer,
 363 you should create two new modules in the Catalyst::Action::Serialize
 364 and Catalyst::Action::Deserialize namespace.  Then assign your new
 365 class to the content-type's you want, and you're done.
 366 .PP
 367 See Catalyst::Action::Serialize and Catalyst::Action::Deserialize
 368 for more information.
 369 .SH "STATUS HELPERS"
 370 .IX Header "STATUS HELPERS"
 371 Since so much of \s-1REST\s0 is in using \s-1HTTP\s0, we provide these Status Helpers.
 372 Using them will ensure that you are responding with the proper codes,
 373 headers, and entities.
 374 .PP
 375 These helpers try and conform to the \s-1HTTP\s0 1.1 Specification.  You can
 376 refer to it at: <http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.
 377 These routines are all implemented as regular subroutines, and as
 378 such require you pass the current context ($c) as the first argument.
 379 .IP "status_ok" 4
 380 .IX Item "status_ok"
 381 Returns a \*(L"200 \s-1OK\s0\*(R" response.  Takes an \*(L"entity\*(R" to serialize.
 382 .Sp
 383 Example:
 384 .Sp
 385 .Vb 6
 386 \&  $self\->status_ok(
 387 \&    $c,
 388 \&    entity => {
 389 \&        radiohead => "Is a good band!",
 390 \&    }
 391 \&  );
 392 .Ve
 393 .IP "status_created" 4
 394 .IX Item "status_created"
 395 Returns a \*(L"201 \s-1CREATED\s0\*(R" response.  Takes an \*(L"entity\*(R" to serialize,
 396 and a \*(L"location\*(R" where the created object can be found.
 397 .Sp
 398 Example:
 399 .Sp
 400 .Vb 7
 401 \&  $self\->status_created(
 402 \&    $c,
 403 \&    location => $c\->req\->uri\->as_string,
 404 \&    entity => {
 405 \&        radiohead => "Is a good band!",
 406 \&    }
 407 \&  );
 408 .Ve
 409 .Sp
 410 In the above example, we use the requested \s-1URI\s0 as our location.
 411 This is probably what you want for most \s-1PUT\s0 requests.
 412 .IP "status_accepted" 4
 413 .IX Item "status_accepted"
 414 Returns a \*(L"202 \s-1ACCEPTED\s0\*(R" response.  Takes an \*(L"entity\*(R" to serialize.
 415 .Sp
 416 Example:
 417 .Sp
 418 .Vb 6
 419 \&  $self\->status_accepted(
 420 \&    $c,
 421 \&    entity => {
 422 \&        status => "queued",
 423 \&    }
 424 \&  );
 425 .Ve
 426 .IP "status_no_content" 4
 427 .IX Item "status_no_content"
 428 Returns a \*(L"204 \s-1NO\s0 \s-1CONTENT\s0\*(R" response.
 429 .IP "status_multiple_choices" 4
 430 .IX Item "status_multiple_choices"
 431 Returns a \*(L"300 \s-1MULTIPLE\s0 \s-1CHOICES\s0\*(R" response. Takes an \*(L"entity\*(R" to serialize, which should
 432 provide list of possible locations. Also takes optional \*(L"location\*(R" for preferred choice.
 433 .IP "status_bad_request" 4
 434 .IX Item "status_bad_request"
 435 Returns a \*(L"400 \s-1BAD\s0 \s-1REQUEST\s0\*(R" response.  Takes a \*(L"message\*(R" argument
 436 as a scalar, which will become the value of \*(L"error\*(R" in the serialized
 437 response.
 438 .Sp
 439 Example:
 440 .Sp
 441 .Vb 4
 442 \&  $self\->status_bad_request(
 443 \&    $c,
 444 \&    message => "Cannot do what you have asked!",
 445 \&  );
 446 .Ve
 447 .IP "status_not_found" 4
 448 .IX Item "status_not_found"
 449 Returns a \*(L"404 \s-1NOT\s0 \s-1FOUND\s0\*(R" response.  Takes a \*(L"message\*(R" argument
 450 as a scalar, which will become the value of \*(L"error\*(R" in the serialized
 451 response.
 452 .Sp
 453 Example:
 454 .Sp
 455 .Vb 4
 456 \&  $self\->status_not_found(
 457 \&    $c,
 458 \&    message => "Cannot find what you were looking for!",
 459 \&  );
 460 .Ve
 461 .IP "gone" 4
 462 .IX Item "gone"
 463 Returns a \*(L"41O \s-1GONE\s0\*(R" response.  Takes a \*(L"message\*(R" argument as a scalar,
 464 which will become the value of \*(L"error\*(R" in the serialized response.
 465 .Sp
 466 Example:
 467 .Sp
 468 .Vb 4
 469 \&  $self\->status_gone(
 470 \&    $c,
 471 \&    message => "The document have been deleted by foo",
 472 \&  );
 473 .Ve
 474 .SH "MANUAL RESPONSES"
 475 .IX Header "MANUAL RESPONSES"
 476 If you want to construct your responses yourself, all you need to
 477 do is put the object you want serialized in \f(CW$c\fR\->stash\->{'rest'}.
 478 .SH "IMPLEMENTATION DETAILS"
 479 .IX Header "IMPLEMENTATION DETAILS"
 480 This Controller ties together Catalyst::Action::REST,
 481 Catalyst::Action::Serialize and Catalyst::Action::Deserialize.  It should be suitable for most applications.  You should be aware that it:
 482 .IP "Configures the Serialization Actions" 4
 483 .IX Item "Configures the Serialization Actions"
 484 This class provides a default configuration for Serialization.  It is currently:
 485 .Sp
 486 .Vb 10
 487 \&  _\|_PACKAGE_\|_\->config(
 488 \&      \*(Aqstash_key\*(Aq => \*(Aqrest\*(Aq,
 489 \&      \*(Aqmap\*(Aq       => {
 490 \&         \*(Aqtext/html\*(Aq          => \*(AqYAML::HTML\*(Aq,
 491 \&         \*(Aqtext/xml\*(Aq           => \*(AqXML::Simple\*(Aq,
 492 \&         \*(Aqtext/x\-yaml\*(Aq        => \*(AqYAML\*(Aq,
 493 \&         \*(Aqapplication/json\*(Aq   => \*(AqJSON\*(Aq,
 494 \&         \*(Aqtext/x\-json\*(Aq        => \*(AqJSON\*(Aq,
 495 \&         \*(Aqtext/x\-data\-dumper\*(Aq => [ \*(AqData::Serializer\*(Aq, \*(AqData::Dumper\*(Aq ],
 496 \&         \*(Aqtext/x\-data\-denter\*(Aq => [ \*(AqData::Serializer\*(Aq, \*(AqData::Denter\*(Aq ],
 497 \&         \*(Aqtext/x\-data\-taxi\*(Aq   => [ \*(AqData::Serializer\*(Aq, \*(AqData::Taxi\*(Aq   ],
 498 \&         \*(Aqapplication/x\-storable\*(Aq   => [ \*(AqData::Serializer\*(Aq, \*(AqStorable\*(Aq ],
 499 \&         \*(Aqapplication/x\-freezethaw\*(Aq => [ \*(AqData::Serializer\*(Aq, \*(AqFreezeThaw\*(Aq ],
 500 \&         \*(Aqtext/x\-config\-general\*(Aq    => [ \*(AqData::Serializer\*(Aq, \*(AqConfig::General\*(Aq ],
 501 \&         \*(Aqtext/x\-php\-serialization\*(Aq => [ \*(AqData::Serializer\*(Aq, \*(AqPHP::Serialization\*(Aq ],
 502 \&      },
 503 \&  );
 504 .Ve
 505 .Sp
 506 You can read the full set of options for this configuration block in
 507 Catalyst::Action::Serialize.
 508 .ie n .IP "Sets a ""begin"" and ""end"" method for you" 4
 509 .el .IP "Sets a \f(CWbegin\fR and \f(CWend\fR method for you" 4
 510 .IX Item "Sets a begin and end method for you"
 511 The \f(CW\*(C`begin\*(C'\fR method uses Catalyst::Action::Deserialize.  The \f(CW\*(C`end\*(C'\fR
 512 method uses Catalyst::Action::Serialize.  If you want to override
 513 either behavior, simply implement your own \f(CW\*(C`begin\*(C'\fR and \f(CW\*(C`end\*(C'\fR actions
 514 and use MRO::Compat:
 515 .Sp
 516 .Vb 3
 517 \&  package Foo::Controller::Monkey;
 518 \&  use Moose;
 519 \&  use namespace::autoclean;
 520 \&
 521 \&  BEGIN { extends \*(AqCatalyst::Controller::REST\*(Aq }
 522 \&
 523 \&  sub begin :Private {
 524 \&    my ($self, $c) = @_;
 525 \&    ... do things before Deserializing ...
 526 \&    $self\->maybe::next::method($c);
 527 \&    ... do things after Deserializing ...
 528 \&  }
 529 \&
 530 \&  sub end :Private {
 531 \&    my ($self, $c) = @_;
 532 \&    ... do things before Serializing ...
 533 \&    $self\->maybe::next::method($c);
 534 \&    ... do things after Serializing ...
 535 \&  }
 536 .Ve
 537 .SH "A MILD WARNING"
 538 .IX Header "A MILD WARNING"
 539 I have code in production using Catalyst::Controller::REST.  That said,
 540 it is still under development, and it's possible that things may change
 541 between releases.  I promise to not break things unnecessarily. :)
 542 .SH "SEE ALSO"
 543 .IX Header "SEE ALSO"
 544 Catalyst::Action::REST, Catalyst::Action::Serialize,
 545 Catalyst::Action::Deserialize
 546 .PP
 547 For help with \s-1REST\s0 in general:
 548 .PP
 549 The \s-1HTTP\s0 1.1 Spec is required reading. http://www.w3.org/Protocols/rfc2616/rfc2616.txt
 550 .PP
 551 Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
 552 .PP
 553 The \s-1REST\s0 Wiki: http://rest.blueoxen.net/cgi\-bin/wiki.pl?FrontPage
 554 .SH "AUTHORS"
 555 .IX Header "AUTHORS"
 556 See Catalyst::Action::REST for authors.
 557 .SH "LICENSE"
 558 .IX Header "LICENSE"
 559 You may distribute this code under the same terms as Perl itself.