NAME

Mojolicious::Plugin::JSONAPI - Mojolicious Plugin for building JSON API compliant applications

VERSION

version 0.3

SYNOPSIS

# Mojolicious

# Using route helpers

sub startup {
    my ($self) = @_;

    $self->plugin('JSONAPI', { namespace => 'api' });

    $self->resource_routes({
        resource => 'post',
        relationships => ['author', 'comments', 'email-templates'],
    });

    # Now the following routes are available:

    # GET '/api/posts' -> to('api-posts#fetch_posts')
    # POST '/api/posts' -> to('api-posts#post_posts')
    # GET '/api/posts/:post_id -> to('api-posts#get_post')
    # PATCH '/api/posts/:post_id -> to('api-posts#patch_post')
    # DELETE '/api/posts/:post_id -> to('api-posts#delete_post')

    # GET '/api/posts/:post_id/relationships/author' -> to('api-posts#get_related_author')
    # POST '/api/posts/:post_id/relationships/author' -> to('api-posts#post_related_author')
    # PATCH '/api/posts/:post_id/relationships/author' -> to('api-posts#patch_related_author')
    # DELETE '/api/posts/:post_id/relationships/author' -> to('api-posts#delete_related_author')

    # GET '/api/posts/:post_id/relationships/comments' -> to('api-posts#get_related_comments')
    # POST '/api/posts/:post_id/relationships/comments' -> to('api-posts#post_related_comments')
    # PATCH '/api/posts/:post_id/relationships/comments' -> to('api-posts#patch_related_comments')
    # DELETE '/api/posts/:post_id/relationships/comments' -> to('api-posts#delete_related_comments')

    # GET '/api/posts/:post_id/relationships/email-templates' -> to('api-posts#get_related_email_templates')
    # POST '/api/posts/:post_id/relationships/email-templates' -> to('api-posts#post_related_email_templates')
    # PATCH '/api/posts/:post_id/relationships/email-templates' -> to('api-posts#patch_related_email_templates')
    # DELETE '/api/posts/:post_id/relationships/email-templates' -> to('api-posts#delete_related_email_templates')

    # You can use the following helpers too:

    $self->resource_document($dbic_row, $options);

    $self->compound_resource_document($dbic_row, $options);

    $self->resource_documents($dbic_resultset, $options);
}

DESCRIPTION

This module intends to supply the user with helper methods that can be used to build a JSON API compliant Mojolicious server. It helps create routes for your resources that conform with the specification, along with supplying helper methods to use when responding to requests.

See http://jsonapi.org/ for the JSON API specification. At the time of writing, the version was 1.0.

OPTIONS

namespace

The prefix that's added to all routes, defaults to 'api'. You can also provided an empty string as the namespace, meaing no prefix will be added.

HELPERS

resource_routes(HashRef $spec)

Creates a set of routes for the given resource. $spec is a hash reference that can consist of the following:

{
    resource        => 'post', # name of resource, required
    controller      => 'api-posts', # name of controller, defaults to "api-{resource_plural}"
    relationships   => ['author', 'comments'], # default is []
}

resource should be a singular noun, which will be turned into it's pluralised version (e.g. "post" -> "posts").

Specifying relationships will create additional routes that fall under the resource.

Routes will point to controller actions, the names of which follow the pattern {http_method}_{resource}, with dashes replaced with underscores (i.e. 'email-templates' -> 'email_templates').

NOTE: Your relationships should be in the correct form (singular/plural) based on the relationship in your schema management system. For example, if you have a resource called 'post' and it has many 'comments', make sure comments is passed in as a plural noun.

render_error(Str $status, ArrayRef $errors, HashRef $data. HashRef $meta)

Renders a JSON response under the required top-level errors key. errors is an array reference of error objects as described in the specification. See Error Objects.

Can optionally provide a reference to the primary data for the route as well as meta information, which will be added to the response as-is. Use resource_document to generate the right structure for this argument.

resource_document

Available in controllers:

$c->resource_document($dbix_row, $options);

See resource_document for usage.

compound_resource_document

Available in controllers:

$c->compound_resource_document($dbix_row, $options);

See compound_resource_document for usage.

resource_documents

Available in controllers:

$c->resource_documents($dbix_resultset, $options);

See resource_documents for usage.

cpanm Mojolicious::Plugin::JSONAPI

perl -MCPAN -e shell
install Mojolicious::Plugin::JSONAPI