# Mojolicious::Plugin::Restify [![Build Status](https://travis-ci.org/kwakwaversal/mojolicious-plugin-restify.svg?branch=master)](https://travis-ci.org/kwakwaversal/mojolicious-plugin-restify)

Route shortcuts & helpers for REST collections for the
[Mojolicious](http://mojolicio.us) web framework.

```perl
  # Mojolicious example (Mojolicious::Lite isn't supported)
  package MyApp;
  use Mojo::Base 'Mojolicious';

  sub startup {
    my $self = shift;

    # imports the `collection' route shortcut and `restify' helpers
    $self->plugin('Restify');

    # add REST collection endpoints manually
    my $r = $self->routes;
    my $accounts = $r->collection('accounts');      # /accounts
    $accounts->collection('invoices');              # /accounts/:accounts_id/invoices

    # or add the equivalent REST routes using the restify helper
    # my $r = $self->routes;
    # $self->restify->routes($r, {accounts => {invoices => undef}});
  }

  # Restify controller depicting the REST actions for the /accounts collection.
  # (The name of the controller is the Mojo::Util::camelized version of the
  # collection path.)
  package MyApp::Controller::Accounts;
  use Mojo::Base 'Mojolicious::Controller';

  sub under {
    my $c = shift;

    # To consistenly get the element's ID relative to the under action, use the
    # helper as shown below. If you need to access an element ID from a
    # collection further up the chain, you can access it from the stash.
    #
    # The naming convention is the name of the collection appended with '_id'.
    # E.g., $c->stash('accounts_id').
    my $account = lookup_account_resource($c->restify->current_id);

    # By stashing the $account here, it will now be available in the delete,
    # read, patch, and update actions. This under action is added to every
    # collection by default to help reduce your code, but can be disabled if
    # you wish.
    $c->stash(account => $account);

    # must return a positive value to continue the dispatch chain
    return 1 if $account;

    # inform the end user that this specific resource does not exist
    $c->reply->not_found and return 0;
  }

  sub create { ... }

  sub delete { ... }

  sub list { ... }

  sub read {
    my $c = shift;

    # account was placed in the stash in the under method
    $c->render(json => $c->stash('account'));
  }

  sub patch { ... }

  sub update { ... }

  1;
```

[Mojolicious::Plugin::Restify](https://metacpan.org/release/Mojolicious-Plugin-Restify)
is a [Mojolicious::Plugin](https://metacpan.org/pod/Mojolicious::Plugin). It
simplifies generating all of the
[Mojolicious::Routes](https://metacpan.org/pod/Mojolicious::Routes) for a
typical REST *collection* endpoint (e.g., `/accounts` or `/invoices>` and maps
the common HTTP verbs (`DELETE`, `GET`, `PATCH`, `POST`, `PUT>` to underlying
controller class methods.

For example, creating a *collection* called `/accounts` would create the routes
as shown below. N.B. The `over` option in the example below corresponds to the
name of a route condition. See [Mojolicious route
conditions](https://metacpan.org/pod/Mojolicious::Routes#conditions).

```perl
  # The collection route shortcut below creates the following routes, and maps
  # them to controllers of the camelized route's name.
  #
  # /accounts           *         accounts
  #   +/                GET       "accounts_list"       Accounts::list
  #   +/                POST      "accounts_create"     Accounts::create
  #   +/:accounts_id    *         "accounts"
  #     +/              *         "accounts_under"      Accounts::under
  #       +/            DELETE    "accounts_delete"     Accounts::delete
  #       +/            GET       "accounts_read"       Accounts::read
  #       +/            PATCH     "accounts_patch"      Accounts::patch
  #       +/            PUT       "accounts_update"     Accounts::update

  # expects the element id (:accounts_id) for this collection to be a uuid
  my $route = $r->collection('accounts', over => 'uuid');
```

[Mojolicious::Plugin::Restify](https://metacpan.org/release/Mojolicious-Plugin-Restify)
tries not to make too many assumptions, but the author's recent experience
writing a REST-based API using
[Mojolicious](https://metacpan.org/release/Mojolicious) has helped shaped this
plugin, and might unwittingly express some of his bias.
