<html><head><title>Mojolicious::Plugin::RESTRoutes</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
BODY {
background: white;
color: black;
font-family: arial,sans-serif;
margin: 0;
padding: 1ex;
}
A:link, A:visited {
background: transparent;
color: #006699;
}
A[href="#POD_ERRORS"] {
background: transparent;
color: #FF0000;
}
DIV {
border-width: 0;
}
DT {
margin-top: 1em;
margin-left: 1em;
}
.pod { margin-right: 20ex; }
.pod PRE {
background: #eeeeee;
border: 1px solid #888888;
color: black;
padding: 1em;
white-space: pre;
}
.pod H1 {
background: transparent;
color: #006699;
font-size: large;
}
.pod H1 A { text-decoration: none; }
.pod H2 A { text-decoration: none; }
.pod H3 A { text-decoration: none; }
.pod H4 A { text-decoration: none; }
.pod H2 {
background: transparent;
color: #006699;
font-size: medium;
}
.pod H3 {
background: transparent;
color: #006699;
font-size: medium;
font-style: italic;
}
.pod H4 {
background: transparent;
color: #006699;
font-size: medium;
font-weight: normal;
}
.pod IMG {
vertical-align: top;
}
.pod .toc A {
text-decoration: none;
}
.pod .toc LI {
line-height: 1.2em;
list-style-type: none;
}
/*]]>*/-->
</style>
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.28,
using Pod::Simple::PullParser v3.28,
under Perl v5.020000 at Thu Jan 22 23:57:46 2015 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#VERSION'>VERSION</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<li class='indexItem indexItem1'><a href='#MOJOLICIOUS_SHORTCUTS'>MOJOLICIOUS SHORTCUTS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#rest_routes'>rest_routes</a>
</ul>
<li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#register'>register</a>
</ul>
<li class='indexItem indexItem1'><a href='#AUTHOR'>AUTHOR</a>
<li class='indexItem indexItem1'><a href='#COPYRIGHT_AND_LICENSE'>COPYRIGHT AND LICENSE</a>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>Mojolicious::Plugin::RESTRoutes - routing helper for RESTful operations</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="VERSION"
>VERSION</a></h1>
<p>version 0.010011</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This Mojolicious plugin adds a routing helper for <a href="http://en.wikipedia.org/wiki/Representational_state_transfer" class="podlinkurl"
>REST</a>ful <a href="http://en.wikipedia.org/wiki/Create,_read,_update_and_delete" class="podlinkurl"
>CRUD</a> operations via HTTP to the app.</p>
<p>The routes are intended,
but not restricted to be used by AJAX applications.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="MOJOLICIOUS_SHORTCUTS"
>MOJOLICIOUS SHORTCUTS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="rest_routes"
>rest_routes</a></h2>
<p>Can be used to easily generate the needed RESTful routes for a resource.</p>
<pre> my $userroute = $self->rest_routes(name => 'user');
# Installs the following routes (given that $r->namespaces == ['My::Mojo']):
# GET /api/users --> My::Mojo::User::rest_list()
# POST /api/users --> My::Mojo::User::rest_create()
# GET /api/users/:userid --> My::Mojo::User::rest_show()
# PUT /api/users/:userid --> My::Mojo::User::rest_update()
# DELETE /api/users/:userid --> My::Mojo::User::rest_remove()</pre>
<p><i>Please note</i>: plural forms will be used in the route, i.e. "users" instead of "user".</p>
<p>You can also chain <code>rest_routes</code>:</p>
<pre> $userroute->rest_routes(name => 'hat', readonly => 1);
# Installs the following additional routes:
# GET /api/users/:userid/hats --> My::Mojo::Hat::rest_list()
# GET /api/users/:userid/hats/:hatid --> My::Mojo::Hat::rest_show()</pre>
<p>The target controller has to implement the following methods:</p>
<ul>
<li><code>rest_list</code></li>
<li><code>rest_create</code></li>
<li><code>rest_show</code></li>
<li><code>rest_update</code></li>
<li><code>rest_remove</code></li>
</ul>
<p><b>Parameters to control the route creation</b></p>
<dl>
<dt><a name="name"
>name</a></dt>
<dd>
<p>The name of the resource, e.g. a "user", a "book" etc. This name will be used to build the route URL as well as the controller name (see example above).</p>
<dt><a name="readonly_(optional)"
>readonly (optional)</a></dt>
<dd>
<p>If set to 1, no create/update/delete routes will be created</p>
<dt><a name="controller_(optional)"
>controller (optional)</a></dt>
<dd>
<p>Default behaviour is to use the resource name to build the CamelCase controller name (this is done by <a href="http://search.cpan.org/perldoc?Mojolicious%3A%3ARoutes%3A%3ARoute" class="podlinkpod"
>Mojolicious::Routes::Route</a>). You can change this by directly specifying the controller's name via the <i>controller</i> attribute.</p>
<p>Note that you have to give the real controller class name (i.e. CamelCased or whatever you class name looks like) including the full namespace.</p>
<pre> $self->rest_routes(name => 'user', controller => 'My::Mojo::Person');
# Installs the following routes:
# GET /api/users --> My::Mojo::Person::rest_list()
# ...</pre>
</dd>
</dl>
<p><b>How to retrieve the parameters / IDs</b></p>
<p>There are two ways to retrieve the IDs given by the client in your <code>rest_show</code>, <code>rest_update</code> and <code>rest_remove</code> methods.</p>
<p>Example request: <code>GET /api/users/5/hats/no9</code></p>
<p>1. New way: the stash entry <code>fm.ids</code> holds a hash with all ids:</p>
<pre> package My::Mojo::Hats;
use Mojo::Base 'Mojolicious::Controller';
sub rest_show {
use Data::Dump qw(dump);
print dump($self->stash('fm.ids'));
# { user => 5, hat => 'no9' }
}</pre>
<p>2. Old way: for each resource there will be a parameter <code>***id</code>, e.g.:</p>
<pre> package My::Mojo::Hat;
use Mojo::Base 'Mojolicious::Controller';
sub rest_show {
my ($self) = @_;
my $user = $self->param('userid');
my $hat = $self->param('hatid');
return $self->render(text => "$userid, $hatid");
# text: "5, no9"
}</pre>
<p>Furthermore, the parameter <code>idname</code> holds the name of the last ID in the route:</p>
<pre> package My::Mojo::Hat;
use Mojo::Base 'Mojolicious::Controller';
sub rest_show {
my $p_name = $self->param('idname');
my $id = $self->param($p_name);
return $self->render(text => sprintf("%s = %s", $p_name, $id || ''));
# text: "hatid = 5"
}</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="register"
>register</a></h2>
<p>Adds the routing helper. Is called by Mojolicious.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Jens Berthold <cpan-mp-restroutes@jebecs.de></p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_AND_LICENSE"
>COPYRIGHT AND LICENSE</a></h1>
<p>This software is Copyright (c) 2015 by Jens Berthold.</p>
<p>This is free software, licensed under:</p>
<pre> The MIT (X11) License</pre>
<!-- end doc -->
</body></html>