NAME
Dancer::Plugin::CRUD - A plugin for writing RESTful apps with Dancer
VERSION
Version 1.03
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;
my $userdb = My::UserDB->new(...);
resource('user',
'read' => sub { $userdb->find(captures()->{'user_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, patch, 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 = captures->{user_id}
create => sub { ... }, # create a new user with params->{user}
delete => sub { ... }, # delete user where id = captures->{user_id}
update => sub { ... }, # update user with params->{user}
patch => sub { ... }, # patches user with params->{user}
prefix => sub {
# prefixed resource in plural
# routes are only possible with regex!
get qr{/foo} => sub { ... },
},
prefix_id => sub {
# prefixed resource in singular with id
# captures->{user_id}
# routes are only possible with regex!
get qr{/bar} => sub { ... },
};
# this defines the following routes:
# prefix_id =>
# GET /user/:user_id/bar
# prefix =>
# GET /users/foo
# index =>
# GET /users.:format
# GET /users
# create =>
# POST /user.:format
# POST /user
# read =>
# GET /user/:id.:format
# GET /user/:id
# delete =>
# DELETE /user/:id.:format
# DELETE /user/:id
# update =>
# PUT /user/:id.:format
# PUT /user/:id
# patch =>
# PATCH /user.:format
# PATCH /userThe routes are created in the above order.
Returns a hash with arrayrefs of all created Dancer::Route objects.
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 '.captures->{foo_id}
}; # GET /foo/123/bar
resource bar =>
read => sub {
return 'foo is '
. captures->{foo_id}
.' and bar is '
. captures->{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 captures names and the suffix of parameterized prefix method:
$Dancer::Plugin::CRUD::SUFFIX = 'Id';
resource 'User' => prefixId => sub { return captures->{'UserId'} };Automatic validation of parameters
Synopsis:
resource foo =>
validation => {
generic => {
checks => [
foo_id => Validate::Tiny::is_like(qr{^\d+})
]
},
},
read => sub {
$foo_id = var('validate')->data('foo_id');
},
;The keyword validation specifies rules for Validation::Tiny.
The parameter input resolves to following order: params('query'), params('body'), captures().
The rules and the result of Dancer::params() are applied to Validate::Tiny::new and stored in var('validate').
The hashref validation accepts seven keywords:
- generic
-
These are generic rules, used in every action. For the actions index and create, the fields
$resource_id are ignored, since they aren't needed. - index, create, read, update, delete
-
These rules are merged together with generic.
- prefix, prefix_id
-
These rules are merged together with generic, but they can only used when
resource()is used in the prefix subs. - wrap
-
These rules apply when in a prefix or prefix_id routine the wrap keyword is used:
resource foo => validation => { wrap => { GET => { bar => { fields => [qw[ name ]] } } } }, prefix => sub { wrap GET => bar => sub { ... } };
The id-fields ($resource_id, ...) are automatically prepended to the fields param of Validate::Tiny. There is no need to define them especially.
An advantage is the feature of stacking resources and to define validation rules only once.
Example:
resource foo =>
validation => {
generic => {
checks => [
foo_id => Validate::Tiny::is_like(qr{^\d+})
]
},
},
prefix_id => sub {
resource bar =>
validation => {
generic => {
checks => [
bar_id => Validate::Tiny::is_like(qr{^\d+})
]
},
},
read => sub {
$foo_id = var('validate')->data('foo_id');
$bar_id = var('validate')->data('foo_id');
},
;
},
;Chaining actions together
To avoid redundant code, the keyword chain may used to define a coderef executing every times the resource (and possible parent resources) is triggered, irrespective of the method.
Example:
resource foo =>
chain => sub { var onetwothree => 123 },
index => sub { return var('onetwothree') }
prefix_id => sub {
resource bar =>
chain => sub { var fourfivesix => 456 },
index => sub { return var('onetwothree').var('fourfivesix') },
;
},
;When resource foo is triggered, the variable onetwothree is set to 123. When resource bar is triggered, the variable onetwothree is set to 123 and, of course, fourfivesix is set to 456.
This is useful to obtain parent objects from DB and store it into the var stack.
WARNING: This feature may change in a future release.
wrap
This keyword wraps validation rules and format accessors. For return values see resource.
Synopsis:
resource foo =>
prefix_id => sub {
wrap GET => bar => sub {
# same as get('/bar', sub { ... });
# and get('/bar.:format', sub { ... });
# var('validate') is also availble,
# when key 'validation' is defined
};
},
;wrap uses the same wrapper as for the actions in resource. Any beviour there also applies here. For a better explaination, these resolves to the same routes:
resource foo => read => sub { ... };
wrap read => foo => sub { ... };The first argument is an CRUD action (index, create, read, update, delete) or a HTTP method (GET, POST, PUT, DELETE, PATCH) and is case-insensitve. The second argument is a route name. A leading slash will be prepended if the route contains to slashes. The third argument is the well known coderef.
Please keep in mind that wrap creates two routes: /$route and /$route.:format.
Returns a list of all created Dancer::Route objects.
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.