The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Mojolicious-Plugin-RESTful-0.1.4
River stage zero No dependents
/ Mojolicious::Plugin::RESTful

NAME

Mojolicious::Plugin::RESTful - A Mojolicious Plugin for RESTful HTTP Actions

VERSION

version 0.1.4

SYNOPSIS

In your RESTful application:


            

              
              
package MyRest;
use Mojo::Base 'Mojolicious';
sub startup {
  my $self = shift;
  $self->plugin("RESTful");
  my $routes = $self->routes;
  $routes->restful("Person");
}
1;

The following routes should be installed:


            

              
              
#
# HTTP    ROUTE             CONTROLLER#ACTION      NAME
#
# ------------Collection-------------
# GET     /people           Person#people_list     "people_list"
# POST    /people           Person#people_create   "people_create"
# OPTIONS /people           Person#people_options  "people_options"
# GET     /people/search    Person#people_search   "people_search"
# GET     /people/count     Person#people_count    "people_count"
#
# -------------Resource--------------
# GET     /people/:person   Person#person_retrieve "person_retrieve"
# DELETE  /people/:person   Person#person_delete   "person_delete"
# PUT     /people/:person   Person#person_update   "person_update"
# PATCH   /people/:person   Person#person_patch    "person_patch"
# OPTIONS /people/:person   Person#person_options  "person_options"
#

For a longer version of parameters:


            

              
              
#
# @param name       is the route identity
# @param controller is the controller class, default is @param name.
# @param methods    is the methods short name for routes
#   l: list,     collection
#   c: create,   collection
#   r: retrieve, resource
#   u: update,   resource
#   d: delete,   resource
#   p: patch,    resource
#   o: options,  collection/resource
#   `lcrudp` is used to detemine to return collection route or resource route.
#
# @param root       is the methods for root routes, used only in chained/nested route.
#   set root as empty('') to disable generating routes in root.
# @param nonresource
#   A HASH ref like:  { search => 'get', convert => 'post' }, which is used to generate the nonresource methods.
#   By default, `restful` short cut will generate `search` and `count` for collection routes.
#   Set nonresource as empty hash ref ({}) to disable nonresource generating methods.
#
# @param under      supposed to support, not funtionally yet.
#
# @return           the chained route for collection or resource
#
$routes->restful(
  name => 'Person',
  controller => 'Person',
  methods => 'lcrudpo',
  root => 'lcrudpo',
  nonresource => {
    search => 'get',
    count => 'get',
  }
);

A chained RESTful routes sample:


            

              
              
$routes->restful('person')->restful('cat'); # name is case-insensitive

generates these routes (person routes not listed):


            

              
              
#
# HTTP    ROUTE             CONTROLLER#ACTION      NAME
#
# GET     /people/:person/cats      Cat#person_cats_list    person_cats_list
# POST    /people/:person/cats      Cat#person_cats_create  person_cats_create
# OPTION  /people/:person/cats      Cat#person_cats_options person_cats_options
#
# GET     /people/:person/cats/:cat Cat#person_cat_retrieve person_cat_retrieve
# PUT     /people/:person/cats/:cat Cat#person_cat_update   person_cat_update
# DELETE  /people/:person/cats/:cat Cat#person_cat_delete   person_cat_delete
# PATCH   /people/:person/cats/:cat Cat#person_cat_patch    person_cat_patch
# OPTION  /people/:person/cats/:cat Cat#person_cat_options  person_cat_options
# *       /people/:person/cats/:cat (chained)               person
#
# GET     /cats                     Cat#cats_list           cats_list
# POST    /cats                     Cat#cats_create         cats_create
# OPTION  /cats                     Cat#cats_options        cats_options
#
# GET     /cats/:cat                Cat#cat_retrieve        cat_retrieve
# PUT     /cats/:cat                Cat#cat_update          cat_update
# DELETE  /cats/:cat                Cat#cat_delete          cat_delete
# PATCH   /cats/:cat                Cat#cat_patch           cat_patch
# OPTION  /cats/:cat                Cat#cat_options         cat_options
# *       /cats/:cat                (chained)               cat
#

DESCRIPTION

This is a Mojolicious plugin adding a RESTful CRUD helper restful to Mojolicious Route.

The idea and some code comes from Mojolicious::Plugin::REST.

The differences are:

  • No under needed.

  • No types support.

This is more convenient for me, feel free to use Mojolicious::Plugin::REST in your stuff.

CONFIGRATION

crud2http

Mojolicious::Plugin::RESTful will generate the methods by default, set this in plugin options:


            

              
              
$app->plugin('RESTful' => {
    crud2http => {
      collection => {
        list => 'get',
        create => 'post',
        options => 'options',
      },
      resource => {
        retrieve => 'get',
        update => 'put',
        delete => 'delete',
        patch => 'patch',
        options => 'options',
      },
    }
  }
);

collection

By default Mojolicious::Plugin::RESTful generate three routes for collections:

  • list => 'get'

    This is used to list collection contains.

  • create => 'post'

    Create an resource should use 'POST'.

  • options => 'options'

    Use this to list options for collection.

resource

By default Mojolicious::Plugin::RESTful generate five routes for resources:

  • retrieve => 'get'

    To retrieve or read resource from a collection.

  • update => 'put'

    To totally update a resource.

  • delete => 'delete'

    To delete a resource.

  • patch => 'patch',

    To update part of the resource.

  • options => 'options'

    To list options for the resource.

METHODS

register

Mojolicious plugin register method.

AUTHOR

Huo Linhe <huolinhe@berrygenomics.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Berry Genomics.

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