.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "Dancer::Plugin::REST 3pm"
.TH Dancer::Plugin::REST 3pm "2022-06-12" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dancer::Plugin::REST \- A plugin for writing RESTful apps with Dancer
.SH "VERSION"
.IX Header "VERSION"
version 0.11
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This plugin helps you write a RESTful webservice with Dancer.
.SH "SYNOPSYS"
.IX Header "SYNOPSYS"
.Vb 1
\&    package MyWebService;
\&
\&    use Dancer;
\&    use Dancer::Plugin::REST;
\&
\&    prepare_serializer_for_format;
\&
\&    get \*(Aq/user/:id.:format\*(Aq => sub {
\&        User\->find(params\->{id});
\&    };
\&
\&    # curl http://mywebservice/user/42.json
\&    { "id": 42, "name": "John Foo", email: "john.foo@example.com"}
\&
\&    # curl http://mywebservice/user/42.yml
\&    \-\-
\&    id: 42
\&    name: "John Foo"
\&    email: "john.foo@example.com"
.Ve
.SH "KEYWORDS"
.IX Header "KEYWORDS"
.SS "prepare_serializer_for_format"
.IX Subsection "prepare_serializer_for_format"
When this pragma is used, a before filter is set by the plugin to automatically
change the serializer when a format is detected in the \s-1URI.\s0
.PP
That means that each route you define with a \fB:format\fR token will trigger a
serializer definition, if the format is known.
.PP
This lets you define all the \s-1REST\s0 actions you like as regular Dancer route
handlers, without explicitly handling the outgoing data format.
.SS "resource"
.IX Subsection "resource"
This keyword lets you declare a resource your application will handle.
.PP
.Vb 5
\&    resource user =>
\&        get    => sub { # return user where id = params\->{id}   },
\&        create => sub { # create a new user with params\->{user} },
\&        delete => sub { # delete user where id = params\->{id}   },
\&        update => sub { # update user with params\->{user}       };
\&
\&    # this defines the following routes:
\&    # GET /user/:id
\&    # GET /user/:id.:format
\&    # POST /user
\&    # POST /user.:format
\&    # DELETE /user/:id
\&    # DELETE /user/:id.:format
\&    # PUT /user/:id
\&    # PUT /user/:id.:format
.Ve
.SS "helpers"
.IX Subsection "helpers"
Some helpers are available. This helper will set an appropriate \s-1HTTP\s0 status for you.
.PP
\fIstatus_ok\fR
.IX Subsection "status_ok"
.PP
.Vb 1
\&    status_ok({users => {...}});
.Ve
.PP
Set the \s-1HTTP\s0 status to 200
.PP
\fIstatus_created\fR
.IX Subsection "status_created"
.PP
.Vb 1
\&    status_created({users => {...}});
.Ve
.PP
Set the \s-1HTTP\s0 status to 201
.PP
\fIstatus_accepted\fR
.IX Subsection "status_accepted"
.PP
.Vb 1
\&    status_accepted({users => {...}});
.Ve
.PP
Set the \s-1HTTP\s0 status to 202
.PP
\fIstatus_bad_request\fR
.IX Subsection "status_bad_request"
.PP
.Vb 1
\&    status_bad_request("user foo can\*(Aqt be found");
.Ve
.PP
Set the \s-1HTTP\s0 status to 400. This function as for argument a scalar that will be used under the key \fBerror\fR.
.PP
\fIstatus_not_found\fR
.IX Subsection "status_not_found"
.PP
.Vb 1
\&    status_not_found("users doesn\*(Aqt exists");
.Ve
.PP
Set the \s-1HTTP\s0 status to 404. This function as for argument a scalar that will be used under the key \fBerror\fR.
.SH "LICENCE"
.IX Header "LICENCE"
This module is released under the same terms as Perl itself.
.SH "AUTHORS"
.IX Header "AUTHORS"
This module has been written by Alexis Sukrieh \f(CW\*(C`<sukria@sukria.net>\*(C'\fR and Franck
Cuny.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Dancer <http://en.wikipedia.org/wiki/Representational_State_Transfer>
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Alexis Sukrieh <sukria@sukria.net>
.IP "\(bu" 4
Franck Cuny <franckc@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 by Alexis Sukrieh.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.