JSONAPI::Document - Turn DBIx results into JSON API documents.
version 0.4
use JSONAPI::Document; use DBIx::Class::Schema; my $jsonapi = JSONAPI::Document->new(); 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'));
This is a plug-and-play Moo class that builds data structures according to the JSON API specification.
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').
Boolean attribute; setting this will make the column keys for each document into kebab-cased-strings instead of snake_cased. Default is false.
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.
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).
Builds a single resource document for the given result row. Will optionally include relationships that contain resource identifiers.
{ id => 1, type => 'authors', attributes => {}, relationships => {}, },
View the resource document specification here.
with_relationships
If true, will introspect the rows relationships and include each of them in the relationships key of the document.
If with_relationships is true, this optional array ref can be provided to include a subset of relations instead of all of them.
Builds the structure for multiple resource documents with a given resultset.
{ data => [ { id => 1, type => 'authors', attributes => {}, relationships => {}, }, ... ] }
See resource_document for a list of options.
resource_document
To install JSONAPI::Document, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JSONAPI::Document
CPAN shell
perl -MCPAN -e shell install JSONAPI::Document
For more information on module installation, please visit the detailed CPAN module installation guide.