NAME

PONAPI::Document - a {json:api} document building class

VERSION

version 0.001002

SYNOPSIS

use PONAPI::Document;

my $document = PONAPI::Document->new(
    version  => $version,
    req_path => $req_path,
    req_base => $req_base,
);

my $resource = $document->add_resource( type => 'foo', id => 1 )
                        ->add_attributes({ ... })
                        ->add_self_link;
$resource->add_relationship(%$_) for ...;

# If we want multiple resources in one response:
$document->convert_to_collection;
$document->add_resource() # go crazy!

# If we have an error at some point:
$document->raise_error( 418, 'TEA TIME' );

# And once we are done, return a valid {json:api} document
# as a perl hash, which you can later turn into JSON.
my $result = $document->build;

DESCRIPTION

PONAPI::Document lets you build {json:api} compliant documents.

You'll want to refer to the {json:api} spec when using this class.

METHODS

• new

  Creates a new document object. Requires version.

  You may optionally provide req_base and req_path.

• req_base

  The base of the request. Used to create links. Empty string by default.

  # Without req_base set:
  '/authors/1'
  
  # With req_base set to 'http://www.mygreatponapisite.com/'
  'http://www.mygreatponapisite.com/authors/1'

• req_path

  Path to the current request. Used to create pagination links.

• set_status

• status

  HTTP status for the request. Default is 200.

• version

  {json:api} version of the request. This must be set when creating the object.

• add_meta( $meta_key => $value )

  Adds an entry to the meta section of the document, under $meta_key.

• add_resource({ type => $type, id => $id })

  Creates a new PONAPI::Document::Builder::Resource object, with type $type and id $id, and adds it to the document.

  You can then call add_relationship and add_attributes on this object, amongst other things; See PONAPI::Document::Builder::Resource for all the ways to add information to this object.

• add_null_resource

  Adds a null resource to the object.

• convert_to_collection

  By default, all documents hold a single resource in their data section. However, if convert_to_collection is called on a resource, the data section will instead hold an arrayref of resources.

  # Originally:
  { data: { type => 'foo', id => 1, attributes => ... } }
  
  # After convert_to_collection
  { data: [ { type => 'foo', id => 1, attributes => ... }, ] }

• is_collection

  Returns true if the object holds a collection.

• add_included({ type => $type, id => $id })

  Similarly to add_resource, returns a PONAPI::Document::Builder::Resource object of the given type and id, and adds it to the included section of the document.

• add_link( $link_type => $url )

• add_links( $link_type => $url, ... )

  Adds links to the links section of the document.

• add_self_link

  Convenience method that adds a link to the current object into the links section.

• add_pagination_links(%links)

  Adds the provided pagination links to the links section.

  $obj->add_pagination_links(
      first => ...,
      self  => ...,
      prev  => ...,
      next  => ...,
  );

• build

  Creates a document out of the current state of the object.

• parent

  Returns the immediate parent of this object, or undef. See also is_root

• is_root

  Returns true if we are the root of the document tree.

• find_root

  Returns the root document.

• raise_error( $http_status, $reason )

  Creates an error document.

• has_errors

• has_errors_builder

• has_included

• has_link

• has_links

• has_links_builder

• has_parent

• has_resource

• has_resource_builders

• has_resources

• has_status

• has_meta

  These do what you would expect.

BUGS, CONTACT AND SUPPORT

For reporting bugs or submitting patches, please use the github bug tracker at https://github.com/mickeyn/PONAPI.

AUTHORS

• Mickey Nasriachi <mickey@cpan.org>

• Stevan Little <stevan@cpan.org>

• Brian Fraser <hugmeir@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Mickey Nasriachi, Stevan Little, Brian Fraser.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.