NAME

JSONAPI::Document - Turn DBIx results into JSON API documents.

VERSION

version 0.7

SYNOPSIS

use JSONAPI::Document;
use DBIx::Class::Schema;

my $jsonapi = JSONAPI::Document->new({ api_url => 'http://example.com/api' });
my $schema = DBIx::Class::Schema->connect(['dbi:SQLite:dbname=:memory:', '', '']);
my $user = $schema->resultset('User')->find(1);

# Builds a simple JSON API document, without any relationships
my $doc = $jsonapi->resource_document($user);

# Same but with all relationships
my $doc = $jsonapi->resource_document($user, { with_relationships => 1 });

# With only the author relationship
my $doc = $jsonapi->resource_document($user, { with_relationships => 1, relationships => ['author'] });

# Fully blown resource document with all relationships and their attributes
my $doc = $jsonapi->compound_resource_document($user);

# Multiple resource documents
my $docs = $jsonapi->resource_documents($schema->resultset('User'));

DESCRIPTION

This is a plug-and-play Moo class that builds data structures according to the JSON API specification.

NOTES

JSON API documents require that you define the type of a document, which this library does using the source_name of the result row. The type is also pluralised using Linua::EN::Inflexion while keeping relationship names intact (i.e. an 'author' relationship will still be called 'author', with the type 'authors').

ATTRIBUTES

api_url

Required; An absolute URL pointing to your servers JSON API namespace.

kebab_case_attrs

Boolean attribute; setting this will make the column keys for each document into kebab-cased-strings instead of snake_cased. Default is false.

attributes_via

The method name to use throughout the creation of the resource document(s) to get the attributes of the resources/relationships. This is useful if you have a object that layers your DBIx results, you can instruct this module to call that method instead of the default, which is get_inflated_columns.

METHODS

compound_resource_document(DBIx::Class::Row|Object $row, HashRef $options)

A compound document is one that includes the resource object along with the data of all its relationships.

Returns a HashRef with the following structure:

{
    data => {
        id => 1,
        type => 'authors',
        attributes => {},
        relationships => {},
    },
    included => [
        {
            id => 1,
            type => 'posts',
            attributes => { ... },
        },
        ...
    ]
}

The following options can be given:

includes

An array reference specifying inclusion of a subset of relationships. By default all the relationships will be included, use this if you only want a subset of relationships (e.g. when accepting the includes query parameter in your application routes).

resource_document(DBIx::Class::Row|Object $row, HashRef $options)

Builds a single resource document for the given result row. Will optionally include relationships that contain resource identifiers.

Returns a HashRef with the following structure:

{
    id => 1,
    type => 'authors',
    attributes => {},
    relationships => {},
},

View the resource document specification here.

The following options can be given:

with_relationships Bool

If true, will introspect the rows relationships and include each of them in the relationships key of the document.

with_attributes Bool

If with_relationships is true, for each resulting row of a relationship, the attributes of that relation will be included.

By default, each relationship will contain a links object. If this option is true, links object will be replaced with attributes.

includes ArrayRef

If with_relationships is true, this optional array ref can be provided to include a subset of relations instead of all of them.

resource_documents(DBIx::Class::Row|Object $row, HashRef $options)

Builds the structure for multiple resource documents with a given resultset.

Returns a HashRef with the following structure:

{
    data => [
        {
            id => 1,
            type => 'authors',
            attributes => {},
            relationships => {},
        },
        ...
    ]
}

See resource_document for a list of options.

cpanm JSONAPI::Document

perl -MCPAN -e shell
install JSONAPI::Document