NAME
Dancer::Plugin::CRUD - A plugin for writing RESTful apps with Dancer
VERSION
Version 1.01
DESCRIPTION
This plugin is derived from Dancer::Plugin::REST and helps you write a RESTful webservice with Dancer.
SYNOPSYS
package MyWebService;
use Dancer;
use Dancer::Plugin::CRUD;
prepare_serializer_for_format;
read '/user/:id.:format' => 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"METHODS
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 URI.
That means that each route you define with a :format token will trigger a serializer definition, if the format is known.
This lets you define all the REST actions you like as regular Dancer route handlers, without explicitly handling the outgoing data format.
resource
This keyword lets you declare a resource your application will handle.
Derived from Dancer::Plugin::REST, this method has rewritten to provide a more slightly convention. get has been renamed to read and three new actions has been added: index, prefix and prefix_id
Also, Text::Pluralize is applied to resource name with count=1 for singular variant and count=2 for plural variant. If you don't provide a singular/plural variant (i.e. resource name contains parenthesis) the singular and the plural becomes same.
The id name is derived from singular resource name, appended with _id.
resource 'user(s)' =>
index => sub { ... }, # return all users
read => sub { ... }, # return user where id = params->{user_id}
create => sub { ... }, # create a new user with params->{user}
delete => sub { ... }, # delete user where id = params->{user_id}
update => sub { ... }, # update user with params->{user}
prefix => sub {
# prefixed resource in plural
read '/foo' => sub { ... },
},
prefix_id => sub {
# prefixed resource in singular with id
# params->{user_id}
read '/bar' => sub { ... },
};
# this defines the following routes:
# prefix_id =>
# GET /user/:user_id/bar
# prefix =>
# GET /users/foo
# read =>
# GET /user/:id.:format
# GET /user/:id
# index =>
# GET /users.:format
# GET /users
# create =>
# POST /user.:format
# POST /user
# delete =>
# DELETE /user/:id.:format
# DELETE /user/:id
# update =>
# PUT /user/:id.:format
# PUT /user/:idThe routes are created in the above order.
Hint: resources can be stacked with prefix/prefix_id:
resource foo =>
prefix => sub {
get '/bar' => sub {
return 'Hi!'
};
}, # GET /foo/bar
prefix_id => sub {
get '/bar' => sub {
return 'Hey '.param('foo_id')
}; # GET /foo/123/bar
resource bar =>
read => sub {
return 'foo is '
. param('foo_id')
.' and bar is '
. param('bar_id')
}
}; # GET /foo/123/bar/456
};When is return value is a HTTP status code (three digits), status(...) is applied to it. A second return value may be the value to be returned to the client itself:
sub {
return 200
};
sub {
return 404 => 'This object has not been found.'
}
sub {
return 201 => { ... }
};
The default HTTP status code ("200 OK") differs in some actions: create response with "201 Created", delete and update response with "202 Accepted".
Change of suffix
The appended suffix, _id for default, can be changed by setting $Dancer::Plugin::CRUD::SUFFIX. This affects both parameter names and the suffix of parameterized prefix method:
$Dancer::Plugin::CRUD::SUFFIX = 'Id';
resource 'User' => prefixId => sub { return param('UserId') };helpers
Some helpers are available. This helper will set an appropriate HTTP status for you.
status_ok
status_ok({users => {...}});Set the HTTP status to 200
status_created
status_created({users => {...}});Set the HTTP status to 201
status_accepted
status_accepted({users => {...}});Set the HTTP status to 202
status_bad_request
status_bad_request("user foo can't be found");Set the HTTP status to 400. This function as for argument a scalar that will be used under the key error.
status_not_found
status_not_found("users doesn't exists");Set the HTTP status to 404. This function as for argument a scalar that will be used under the key error.
LICENCE
This module is released under the same terms as Perl itself.
AUTHORS
This module has been rewritten by David Zurborg <zurborg@cpan.org>, based on code written by Alexis Sukrieh <sukria@sukria.net> and Franck Cuny.
SEE ALSO
Dancer http://en.wikipedia.org/wiki/Representational_State_Transfer Dancer::Plugin::REST Text::Pluralize
AUTHORS
David Zurborg <zurborg@cpan.org>
Alexis Sukrieh <sukria@sukria.net> (Author of Dancer::Plugin::REST)
Franck Cuny <franckc@cpan.org> (Author of Dancer::Plugin::REST)
BUGS
Please report any bugs or feature requests trough my project management tool at http://development.david-zurb.org/projects/libdancer-plugin-crud-perl/issues/new. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Dancer::Plugin::CRUDYou can also look for information at:
Redmine: Homepage of this module
http://development.david-zurb.org/projects/libdancer-plugin-crud-perl
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by David Zurborg <zurborg@cpan.org>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.