++ed by:

1 PAUSE user
1 non-PAUSE user.

Ali Zia
and 2 contributors


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


version 0.4


    # Mojolicious

    # Using route helpers

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

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

            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);


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.



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.


This is passed to the constructor of JSONAPI::Document which will kebab case the attribute keys of each record (i.e. '_' to '-').


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 Str

The resources name. Should be a singular noun, which will be turned into it's pluralised version (e.g. "post" -> "posts") automatically where necessary.

controller Str

The controller name where the actions are to be stored. Defaults to "api-{resource}", where resource is in its pluralised form.

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').

router Mojolicious::Routes

The parent route to use for the resource. Optional.

Provide your own router if you plan to use under for your resource.

NOTE: Providing your own router assumes that the router is under the same namespace already, so the resource routes won't specify the namespace themselves.


 my $under_api = $r->under('/api')->to('OAuth#is_authenticated');
     router => $under_api,
     resource => 'post',
relationships ArrayRef

The relationships belonging to the resource. Defaults to an empty array ref.

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

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.


Available in controllers:

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

See resource_document for usage.


Available in controllers:

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

See compound_resource_document for usage.


Available in controllers:

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

See resource_documents for usage.