The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dancer-Plugin-CRUD-1.031
River stage zero No dependents
++
/ Dancer::Plugin::CRUD

NAME

Dancer::Plugin::CRUD - A plugin for writing RESTful apps with Dancer

VERSION

version 1.031

DESCRIPTION

This plugin is derived from Dancer::Plugin::REST and helps you write a RESTful webservice with Dancer.

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 /user

The 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 keywords chain and chain_id may used to define coderefs called every time the resource (and possible parent resources) is triggered, respective of the method.

chain applies to method index only. chain_id (where the suffix _id depends on what $SUFFIX says) applies to all other methods. chain_id is called with a single parameter: the value of the corresponding capture.

Example:

    resource foo =>
                chain_id => sub { var my_foo_id => shift },
                read => sub { return var('my_foo_id') }
        prefix_id => sub {
            resource bar =>
                                chain_id => sub { var my_bar_id => shift },
                                read => sub { return var('my_foo_id').var('my_bar_id') },
                        ;
        },
        ;

When resource /foo/123 is triggered, the variable my_foo_id is set to 123 and the single text 123 is returned. When resource /foo/123/bar/456 is triggered, the variable my_foo_id is set to 123 and, of course, my_bar_id is set to 456 and the single return text is 123456.

This is useful to obtain parent objects from DB and store it into the var stack.

HINT: In a earlier release the keyword chain applied to all methods. If you have ever used version 1.03, please keep in mind that this behaviour has changed meanwhile.

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.

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"

SEE ALSO

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/zurborg/libdancer-plugin-crud-perl/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

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)

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by David Zurborg.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.