.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Catalyst::Controller::REST 3"
.TH Catalyst::Controller::REST 3 "2007-07-07" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Catalyst::Controller::REST \- A RESTful controller 
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    package Foo::Controller::Bar;
.Ve
.PP
.Vb 1
\&    use base 'Catalyst::Controller::REST';
.Ve
.PP
.Vb 1
\&    sub thing : Local : ActionClass('REST') { }
.Ve
.PP
.Vb 3
\&    # Answer GET requests to "thing"
\&    sub thing_GET {
\&       my ( $self, $c ) = @_;
.Ve
.PP
.Vb 10
\&       # Return a 200 OK, with the data in entity
\&       # serialized in the body 
\&       $self->status_ok(
\&            $c, 
\&            entity => {
\&                some => 'data',
\&                foo  => 'is real bar-y',
\&            },
\&       );
\&    }
.Ve
.PP
.Vb 4
\&    # Answer PUT requests to "thing"
\&    sub thing_PUT { 
\&      .. some action ..
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Catalyst::Controller::REST implements a mechanism for building
RESTful services in Catalyst.  It does this by extending the
normal Catalyst dispatch mechanism to allow for different 
subroutines to be called based on the \s-1HTTP\s0 Method requested, 
while also transparently handling all the serialization/deserialization for
you.
.PP
This is probably best served by an example.  In the above
controller, we have declared a Local Catalyst action on
\&\*(L"sub thing\*(R", and have used the ActionClass('\s-1REST\s0').  
.PP
Below, we have declared \*(L"thing_GET\*(R" and \*(L"thing_PUT\*(R".  Any
\&\s-1GET\s0 requests to thing will be dispatched to \*(L"thing_GET\*(R", 
while any \s-1PUT\s0 requests will be dispatched to \*(L"thing_PUT\*(R".  
.PP
Any unimplemented \s-1HTTP\s0 methods will be met with a \*(L"405 Method Not Allowed\*(R"
response, automatically containing the proper list of available methods.  You
can override this behavior through implementing a custom
\&\f(CW\*(C`thing_not_implemented\*(C'\fR method.  
.PP
If you do not provide an \s-1OPTIONS\s0 handler, we will respond to any \s-1OPTIONS\s0
requests with a \*(L"200 \s-1OK\s0\*(R", populating the Allowed header automatically.
.PP
Any data included in \f(CW\*(C`$c\->stash\->{'rest'}\*(C'\fR will be serialized for you.
The serialization format will be selected based on the content-type
of the incoming request.  It is probably easier to use the \*(L"\s-1STATUS\s0 \s-1HELPERS\s0\*(R",
which are described below.
.PP
The \s-1HTTP\s0 \s-1POST\s0, \s-1PUT\s0, and \s-1OPTIONS\s0 methods will all automatically deserialize the
contents of \f(CW$c\fR\->request\->body based on the requests content-type header.
A list of understood serialization formats is below.
.PP
If we do not have (or cannot run) a serializer for a given content\-type, a 415
\&\*(L"Unsupported Media Type\*(R" error is generated. 
.PP
To make your Controller RESTful, simply have it
.PP
.Vb 1
\&  use base 'Catalyst::Controller::REST';
.Ve
.SH "SERIALIZATION"
.IX Header "SERIALIZATION"
Catalyst::Controller::REST will automatically serialize your
responses, and deserialize any \s-1POST\s0, \s-1PUT\s0 or \s-1OPTIONS\s0 requests. It evaluates
which serializer to use by mapping a content-type to a Serialization module.
We select the content-type based on: 
.IP "\fBThe Content-Type Header\fR" 2
.IX Item "The Content-Type Header"
If the incoming \s-1HTTP\s0 Request had a Content-Type header set, we will use it.
.IP "\fBThe content-type Query Parameter\fR" 2
.IX Item "The content-type Query Parameter"
If this is a \s-1GET\s0 request, you can supply a content-type query parameter.
.IP "\fBEvaluating the Accept Header\fR" 2
.IX Item "Evaluating the Accept Header"
Finally, if the client provided an Accept header, we will evaluate
it and use the best-ranked choice.  
.SH "AVAILABLE SERIALIZERS"
.IX Header "AVAILABLE SERIALIZERS"
A given serialization mechanism is only available if you have the underlying
modules installed.  For example, you can't use XML::Simple if it's not already
installed.  
.PP
In addition, each serializer has it's quirks in terms of what sorts of data
structures it will properly handle.  Catalyst::Controller::REST makes
no attempt to svae you from yourself in this regard. :) 
.ie n .IP """text/x\-yaml""\fR => \f(CW""YAML::Syck""" 2
.el .IP "\f(CWtext/x\-yaml\fR => \f(CWYAML::Syck\fR" 2
.IX Item "text/x-yaml => YAML::Syck"
Returns \s-1YAML\s0 generated by YAML::Syck.
.ie n .IP """text/html""\fR => \f(CW""YAML::HTML""" 2
.el .IP "\f(CWtext/html\fR => \f(CWYAML::HTML\fR" 2
.IX Item "text/html => YAML::HTML"
This uses YAML::Syck and URI::Find to generate \s-1YAML\s0 with all URLs turned
to hyperlinks.  Only useable for Serialization.
.ie n .IP """text/x\-json""\fR => \f(CW""JSON::Syck""" 2
.el .IP "\f(CWtext/x\-json\fR => \f(CWJSON::Syck\fR" 2
.IX Item "text/x-json => JSON::Syck"
Uses JSON::Syck to generate \s-1JSON\s0 output
.ie n .IP """text/x\-data\-dumper""\fR => \f(CW""Data::Serializer""" 2
.el .IP "\f(CWtext/x\-data\-dumper\fR => \f(CWData::Serializer\fR" 2
.IX Item "text/x-data-dumper => Data::Serializer"
Uses the Data::Serializer module to generate Data::Dumper output.
.ie n .IP """text/x\-data\-denter""\fR => \f(CW""Data::Serializer""" 2
.el .IP "\f(CWtext/x\-data\-denter\fR => \f(CWData::Serializer\fR" 2
.IX Item "text/x-data-denter => Data::Serializer"
Uses the Data::Serializer module to generate Data::Denter output.
.ie n .IP """text/x\-data\-taxi""\fR => \f(CW""Data::Serializer""" 2
.el .IP "\f(CWtext/x\-data\-taxi\fR => \f(CWData::Serializer\fR" 2
.IX Item "text/x-data-taxi => Data::Serializer"
Uses the Data::Serializer module to generate Data::Taxi output.
.ie n .IP """application/x\-storable""\fR => \f(CW""Data::Serializer""" 2
.el .IP "\f(CWapplication/x\-storable\fR => \f(CWData::Serializer\fR" 2
.IX Item "application/x-storable => Data::Serializer"
Uses the Data::Serializer module to generate Storable output.
.ie n .IP """application/x\-freezethaw""\fR => \f(CW""Data::Serializer""" 2
.el .IP "\f(CWapplication/x\-freezethaw\fR => \f(CWData::Serializer\fR" 2
.IX Item "application/x-freezethaw => Data::Serializer"
Uses the Data::Serializer module to generate FreezeThaw output.
.ie n .IP """text/x\-config\-general""\fR => \f(CW""Data::Serializer""" 2
.el .IP "\f(CWtext/x\-config\-general\fR => \f(CWData::Serializer\fR" 2
.IX Item "text/x-config-general => Data::Serializer"
Uses the Data::Serializer module to generate Config::General output.
.ie n .IP """text/x\-php\-serialization""\fR => \f(CW""Data::Serializer""" 2
.el .IP "\f(CWtext/x\-php\-serialization\fR => \f(CWData::Serializer\fR" 2
.IX Item "text/x-php-serialization => Data::Serializer"
Uses the Data::Serializer module to generate PHP::Serialization output.
.ie n .IP """text/xml""\fR => \f(CW""XML::Simple""" 2
.el .IP "\f(CWtext/xml\fR => \f(CWXML::Simple\fR" 2
.IX Item "text/xml => XML::Simple"
Uses XML::Simple to generate \s-1XML\s0 output.  This is probably not suitable
for any real heavy \s-1XML\s0 work. Due to XML::Simples requirement that the data
you serialize be a \s-1HASHREF\s0, we transform outgoing data to be in the form of:
.Sp
.Vb 1
\&  { data => $yourdata }
.Ve
.IP "View" 2
.IX Item "View"
Uses a regular Catalyst view.  For example, if you wanted to have your 
\&\f(CW\*(C`text/html\*(C'\fR and \f(CW\*(C`text/xml\*(C'\fR views rendered by \s-1TT:\s0
.Sp
.Vb 2
\&        'text/html' => [ 'View', 'TT' ],
\&        'text/xml'  => [ 'View', 'XML' ],
.Ve
.Sp
Will do the trick nicely. 
.PP
By default, Catalyst::Controller::REST will return a \f(CW\*(C`415 Unsupported Media Type\*(C'\fR
response if an attempt to use an unsupported content-type is made.  You
can ensure that something is always returned by setting the \f(CW\*(C`default\*(C'\fR
config option:
.PP
.Vb 1
\&   __PACKAGE__->config->{'serialize'}->{'default'} = 'text/x-yaml';
.Ve
.PP
Would make it always fall back to the serializer plugin defined for text/x\-yaml.
.PP
Implementing new Serialization formats is easy!  Contributions
are most welcome!  See Catalyst::Action::Serialize and
Catalyst::Action::Deserialize for more information.
.SH "CUSTOM SERIALIZERS"
.IX Header "CUSTOM SERIALIZERS"
If you would like to implement a custom serializer, you should create two new
modules in the Catalyst::Action::Serialize and
Catalyst::Action::Deserialize namespace.  Then assign your new class
to the content\-type's you want, and you're done.
.SH "STATUS HELPERS"
.IX Header "STATUS HELPERS"
Since so much of \s-1REST\s0 is in using \s-1HTTP\s0, we provide these Status Helpers.
Using them will ensure that you are responding with the proper codes,
headers, and entities.
.PP
These helpers try and conform to the \s-1HTTP\s0 1.1 Specification.  You can
refer to it at: <http://www.w3.org/Protocols/rfc2616/rfc2616.txt>.  
These routines are all implemented as regular subroutines, and as
such require you pass the current context ($c) as the first argument.
.IP "status_ok" 4
.IX Item "status_ok"
Returns a \*(L"200 \s-1OK\s0\*(R" response.  Takes an \*(L"entity\*(R" to serialize.
.Sp
Example:
.Sp
.Vb 6
\&  $self->status_ok(
\&    $c, 
\&    entity => {
\&        radiohead => "Is a good band!",
\&    }
\&  );
.Ve
.IP "status_created" 4
.IX Item "status_created"
Returns a \*(L"201 \s-1CREATED\s0\*(R" response.  Takes an \*(L"entity\*(R" to serialize,
and a \*(L"location\*(R" where the created object can be found.
.Sp
Example:
.Sp
.Vb 7
\&  $self->status_created(
\&    $c, 
\&    location => $c->req->uri->as_string,
\&    entity => {
\&        radiohead => "Is a good band!",
\&    }
\&  );
.Ve
.Sp
In the above example, we use the requested \s-1URI\s0 as our location.
This is probably what you want for most \s-1PUT\s0 requests.
.IP "status_accepted" 4
.IX Item "status_accepted"
Returns a \*(L"202 \s-1ACCEPTED\s0\*(R" response.  Takes an \*(L"entity\*(R" to serialize.
.Sp
Example:
.Sp
.Vb 6
\&  $self->status_accepted(
\&    $c, 
\&    entity => {
\&        status => "queued",
\&    }
\&  );
.Ve
.IP "status_bad_request" 4
.IX Item "status_bad_request"
Returns a \*(L"400 \s-1BAD\s0 \s-1REQUEST\s0\*(R" response.  Takes a \*(L"message\*(R" argument
as a scalar, which will become the value of \*(L"error\*(R" in the serialized
response.
.Sp
Example:
.Sp
.Vb 4
\&  $self->status_bad_request(
\&    $c, 
\&    message => "Cannot do what you have asked!",
\&  );
.Ve
.IP "status_not_found" 4
.IX Item "status_not_found"
Returns a \*(L"404 \s-1NOT\s0 \s-1FOUND\s0\*(R" response.  Takes a \*(L"message\*(R" argument
as a scalar, which will become the value of \*(L"error\*(R" in the serialized
response.
.Sp
Example:
.Sp
.Vb 4
\&  $self->status_not_found(
\&    $c, 
\&    message => "Cannot find what you were looking for!",
\&  );
.Ve
.SH "MANUAL RESPONSES"
.IX Header "MANUAL RESPONSES"
If you want to construct your responses yourself, all you need to
do is put the object you want serialized in \f(CW$c\fR\->stash\->{'rest'}.
.SH "IMPLEMENTATION DETAILS"
.IX Header "IMPLEMENTATION DETAILS"
This Controller ties together Catalyst::Action::REST,
Catalyst::Action::Serialize and Catalyst::Action::Deserialize.  It should be suitable for most applications.  You should be aware that it:
.IP "Configures the Serialization Actions" 4
.IX Item "Configures the Serialization Actions"
This class provides a default configuration for Serialization.  It is currently:
.Sp
.Vb 21
\&  __PACKAGE__->config(
\&      serialize => {
\&         'stash_key' => 'rest',
\&         'map'       => {
\&            'text/html'          => 'YAML::HTML',
\&            'text/xml'           => 'XML::Simple',
\&            'text/x-yaml'        => 'YAML',
\&            'text/x-json'        => 'JSON',
\&            'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
\&            'text/x-data-denter' => [ 'Data::Serializer', 'Data::Denter' ],
\&            'text/x-data-taxi'   => [ 'Data::Serializer', 'Data::Taxi'   ],
\&            'application/x-storable'    => [ 'Data::Serializer', 'Storable'     
\&],
\&            'application/x-freezethaw'  => [ 'Data::Serializer', 'FreezeThaw'   
\&],
\&            'text/x-config-general' => [ 'Data::Serializer', 'Config::General' ]
\&,
\&            'text/x-php-serialization' => [ 'Data::Serializer', 'PHP::Serialization' ],
\&          },
\&      }
\&  );
.Ve
.Sp
You can read the full set of options for this configuration block in
Catalyst::Action::Serialize.
.ie n .IP "Sets a ""begin""\fR and \f(CW""end"" method for you" 4
.el .IP "Sets a \f(CWbegin\fR and \f(CWend\fR method for you" 4
.IX Item "Sets a begin and end method for you"
The \f(CW\*(C`begin\*(C'\fR method uses Catalyst::Action::Deserialize.  The \f(CW\*(C`end\*(C'\fR
method uses Catalyst::Action::Serialize.  If you want to override
either behavior, simply implement your own \f(CW\*(C`begin\*(C'\fR and \f(CW\*(C`end\*(C'\fR actions
and use \s-1NEXT:\s0
.Sp
.Vb 2
\&  my Foo::Controller::Monkey;
\&  use base qw(Catalyst::Controller::REST);
.Ve
.Sp
.Vb 6
\&  sub begin :Private {
\&    my ($self, $c) = @_;
\&    ... do things before Deserializing ...
\&    $self->NEXT::begin($c); 
\&    ... do things after Deserializing ...
\&  }
.Ve
.Sp
.Vb 6
\&  sub end :Private {
\&    my ($self, $c) = @_;
\&    ... do things before Serializing ...
\&    $self->NEXT::end($c); 
\&    ... do things after Serializing ...
\&  }
.Ve
.SH "A MILD WARNING"
.IX Header "A MILD WARNING"
I have code in production using Catalyst::Controller::REST.  That said,
it is still under development, and it's possible that things may change
between releases.  I promise to not break things unneccesarily. :)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Catalyst::Action::REST, Catalyst::Action::Serialize,
Catalyst::Action::Deserialize
.Sp
For help with \s-1REST\s0 in general:
.Sp
The \s-1HTTP\s0 1.1 Spec is required reading. http://www.w3.org/Protocols/rfc2616/rfc2616.txt
.Sp
Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer
.Sp
The \s-1REST\s0 Wiki: http://rest.blueoxen.net/cgi\-bin/wiki.pl?FrontPage
.SH "AUTHOR"
.IX Header "AUTHOR"
Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
.Sp
Marchex, Inc. paid me while I developed this module.  (http://www.marchex.com)
.SH "LICENSE"
.IX Header "LICENSE"
You may distribute this code under the same terms as Perl itself.