/ 
Dancer-Plugin-CRUD-1.01
River stage zero No dependents
/ Dancer::Plugin::CRUD

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/:id

The 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::CRUD

You can also look for information at:

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.