Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kwakwaversal/mojolicious-plugin-restify

Route shortcuts & helpers for REST collections - https://metacpan.org/pod/Mojolicious::Plugin::Restify
https://github.com/kwakwaversal/mojolicious-plugin-restify

mojolicious perl

Last synced: about 1 month ago
JSON representation

Route shortcuts & helpers for REST collections - https://metacpan.org/pod/Mojolicious::Plugin::Restify

Awesome Lists containing this project

README 

        
# 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 with an ARRAYREF (the helper will

    # create chained routes from the path 'accounts/invoices' so you don't need

    # to set ['accounts', 'accounts/invoices'])

    my $r = $self->routes;

    $self->restify->routes($r, ['accounts/invoices']);



    # or add the equivalent REST routes with a HASHREF (might be easier to

    # visualise how collections are chained together)

    my $r = $self->routes;

    $self->restify->routes($r, {

      accounts => {

        invoices => undef

      }

    });

  }

```



Next create your controller for accounts.



```perl

  # 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 resource_lookup {

    my $c = shift;



    # To consistenly get the element's ID relative to the resource_lookup

    # 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 = your_lookup_account_resource_func($c->restify->current_id);



    # By stashing the $account here, it will now be available in the delete,

    # read, patch, and update actions. This resource_lookup action is optional,

    # but added to every collection by default to help reduce your code.

    $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 resource_lookup action

    $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.

  #

  # Pattern           Methods   Name                        Class::Method Name

  # -------           -------   ----                        ------------------

  # /accounts         *         accounts

  #   +/              GET       "accounts_list"             Accounts::list

  #   +/              POST      "accounts_create"           Accounts::create

  #   +/:accounts_id  *         "accounts"

  #     +/            *         "accounts_resource_lookup"  Accounts::resource_lookup

  #       +/          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.