NAME

Mojolicious::Plugin::REST - Mojolicious Plugin for RESTful operations

VERSION

version 0.005

SYNOPSIS

# In Mojolicious application
$self->plugin( 'REST', { prefix => 'api', version => 'v1', } );

$self->routes->rest_routes( name => 'Account' );

# Installs following routes:
# +-------------+-----------------------------+-------------------------+
# | HTTP Method |             URL             |          Route          |
# +-------------+-----------------------------+-------------------------+
# | GET         | /api/v1/accounts            | Account::list_accounts  |
# | POST        | /api/v1/accounts            | Account::create_account |
# | GET         | /api/v1/accounts/:accountId | Account::read_account   |
# | PUT         | /api/v1/accounts/:accountId | Account::update_account |
# | DELETE      | /api/v1/accounts/:accountId | Account::delete_account |
# +-------------+-----------------------------+-------------------------+

$routes->rest_routes( name => 'Feature', under => 'Account' );

# Installs following routes:
# +-------------+-------------------------------------------------+---------------------------------+
# | HTTP Method |                       URL                       |              Route              |
# +-------------+-------------------------------------------------+---------------------------------+
# | GET         | /api/v1/accounts/:accountId/features            | Feature::list_account_features  |
# | POST        | /api/v1/accounts/:accountId/features            | Feature::create_account_feature |
# | GET         | /api/v1/accounts/:accountId/features/:featureId | Feature::read_account_feature   |
# | PUT         | /api/v1/accounts/:accountId/features/:featureId | Feature::update_account_feature |
# | DELETE      | /api/v1/accounts/:accountId/features/:featureId | Feature::delete_account_feature |
# +-------------+-------------------------------------------------+---------------------------------+

$routes->rest_routes( name => 'Product', under => 'Account', types => [qw(FTP SSH)] );

# Installs following routes:
# +-------------+------------------------------------------+--------------------------------------+
# | HTTP Method |                   URL                    |                Route                 |
# +-------------+------------------------------------------+--------------------------------------+
# | GET         | /api/v1/accounts/:accountId/products     | Product::list_account_products       |
# | POST        | /api/v1/accounts/:accountId/products     | Product::create_account_product      |
# | GET         | /api/v1/accounts/:accountId/products/FTP | Product::FTP::read_account_product   |
# | PUT         | /api/v1/accounts/:accountId/products/FTP | Product::FTP::update_account_product |
# | DELETE      | /api/v1/accounts/:accountId/products/FTP | Product::FTP::delete_account_product |
# | GET         | /api/v1/accounts/:accountId/products/SSH | Product::SSH::read_account_product   |
# | PUT         | /api/v1/accounts/:accountId/products/SSH | Product::SSH::update_account_product |
# | DELETE      | /api/v1/accounts/:accountId/products/SSH | Product::SSH::delete_account_product |
# +-------------+------------------------------------------+--------------------------------------+

DESCRIPTION

Mojolicious::Plugin::REST adds various helpers for RESTful CRUD operations via HTTP to the app.

As much as possible, it tries to follow RESTful API Design principles from Apigee.

Used in conjuction with Mojolicious::Controller::REST, this module makes building RESTful application a breeze.

This module is inspired from Mojolicious::Plugin::RESTRoutes.

MOJOLICIOUS HELPERS

rest_routes

A routes shourtcut to easily add RESTful routes for a resource.

MOJOLICIOUS HOOKS

This module installs an before_render application hook, which gurantees JSON output. Refer Mojolicious::Controller::REST documentation for output format.

OPTIONS

Following options can be used to control route creation:

name

The name of the resource, e.g. 'User'. This name will be used to build the route URL as well as the controller name.

readonly

If true, no create, update or delete routes will be created.

controller

By default, resource name will be converted to CamelCase controller name. You can change it by providing controller name.

If customized, this option needs a full namespace of the controller class.

under

This option can be used for associations.

types

This option can be used to specify types of resources available in application.

PLUGIN OPTIONS

prefix

If present, this option will be added before every route created.

version

If present, api version given will be added before every route created (but after prefix).

http2crud

If present, given HTTP to CRUD mapping will be used to determine method names. Default mapping:

get     ->  read
post    ->  create
put     ->  update
delete  ->  delete
list    ->  list

AUTHOR

Abhishek Shende <abhishekisnot@gmail.com>

CONTRIBUTOR

Vincent HETRU <vincent.hetru@13pass.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Abhishek Shende.

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