Provided by: libponapi-client-perl_0.002012-1_all 
NAME
PONAPI::Client - Client to a {JSON:API} service (http://jsonapi.org/) v1.0
VERSION
version 0.002012
SYNOPSIS
use PONAPI::Client;
my $client = PONAPI::Client->new(
host => $host,
port => $port,
);
$client->retrieve_all( type => $type );
$client->retrieve(
type => $type,
id => $id,
);
$client->retrieve_relationships(
type => $type,
id => $id,
rel_type => $rel_type,
);
$client->retrieve_by_relationship(
type => $type,
id => $id,
rel_type => $rel_type,
);
$client->create(
type => $type,
data => {
attributes => { ... },
relationships => { ... },
},
);
$client->delete(
type => $type,
id => $id,
);
$client->update(
type => $type,
id => $id,
data => {
type => $type,
id => $id,
attributes => { ... },
relationships => { ... },
}
);
$client->delete_relationships(
type => $type,
id => $id,
rel_type => $rel_type,
data => [
{ type => $rel_type, id => $rel_id },
...
],
);
$client->create_relationships(
type => $type,
id => $id,
rel_type => $rel_type,
data => [
{ type => $rel_type, id => $rel_id },
...
],
);
$client->update_relationships(
type => $type,
id => $id,
rel_type => $rel_type,
# for a one-to-one:
data => { type => $rel_type, id => $rel_id },
# or for a one-to-many:
data => [
{ type => $rel_type, id => $rel_id },
...
],
);
# If the endpoint uses an uncommon url format:
$client->retrieve(
type => 'foo',
id => 43,
# Will generate a request to
# host:port/type_foo_id_43
uri_template => "type_{type}_id_{id}",
);
DESCRIPTION
"PONAPI::Client" is a {JSON:API} <http://jsonapi.org/> compliant client; it should be able
to communicate with any API-compliant service.
The client does a handful of checks required by the spec, then uses Hijk to communicate
with the service.
In most cases, all API methods return a response document:
my $response = $client->retrieve(...);
In list context however, all api methods will return the request status and the document:
my ($status, $response) = $client->retrieve(...)
Response documents will look something like these:
# Successful retrieve(type => 'articles', id => 2)
{
jsonapi => { version => "1.0" },
links => { self => "/articles/2" },
data => { ... },
meta => { ... }, # May not be there
included => [ ... ], # May not be there, see C<include>
}
# Successful retrieve_all( type => 'articles' )
{
jsonapi => { version => "1.0" },
links => { self => "/articles" }, # May include pagination links
data => [
{ ... },
{ ... },
...
],
meta => { ... }, # May not be there
included => [ ... ], # May not be there, see C<include>
}
# Successful create(type => 'foo', data => { ... })
{
jsonapi => { version => "1.0" },
links => { self => "/foo/$created_id" },
data => { type => 'foo', id => $created_id },
}
# Successful update(type => 'foo', id => 2, data => { ... })
{
jsonapi => { version => "1.0" },
links => { self => "/foo/2" }, # may not be there
meta => { ... }, # may not be there
}
# Error, see http://jsonapi.org/format/#error-objects
{
jsonapi => { version => "1.0" },
errors => [
{ ... }, # error 1
... # potentially others
],
}
However, there are situations where the server may respond with a "204 No Content" and no
response document; depending on the situation, it might be worth checking the status.
METHODS
new
Creates a new "PONAPI::Client" object. Takes a couple of attributes:
host
The hostname (or IP address) of the service. Defaults to localhost.
port
Port of the service. Defaults to 5000.
send_version_header
Sends a "X-PONAPI-Client-Version" header set to the {JSON:API} version the client
supports. Defaults to true.
retrieve_all
retrieve_all( type => $type, %optional_arguments )
Retrieves all resources of the given type. In SQL, this is similar to "SELECT * FROM
$type".
This handles several arguments:
fields
Spec <http://jsonapi.org/format/#fetching-sparse-fieldsets>.
Instead of returning every attribute and relationship from a given resource, "fields"
can be used to specify exactly what is returned.
This excepts a hashref of arrayrefs, where the keys are types, and the values are
either attribute names, or relationship names.
$client->retrieve_all(
type => 'people',
fields => { people => [ 'name', 'age' ] }
)
Note that an attribute not being in fields means the opposite to an attribute having
empty fields:
# No attributes or relationships for both people and comments
$client->retrieve_all(
type => 'people',
fields => { people => [], comments => [] },
);
# No attributes or relationships for comments, but
# ALL attributes and relationships for people
$client->retrieve_all(
type => 'people',
fields => { comments => [] },
);
include
Spec <http://jsonapi.org/format/#fetching-includes>.
"include" can be used to fetch related resources. The example below is fetching both
all the people, and all comments made by those people:
my $response = $client->retrieve_all(
type => 'people',
include => ['comments']
);
"include" expects an arrayref of relationship names. In the response, the resources
fetched will be in an arrayref under the top-level "included" key:
say $_->{attributes}{body} for @{ $response->{included} }
page
Spec <http://jsonapi.org/format/#fetching-pagination>.
Requests that the server paginate the results. Each endpoint may have different
pagination rules.
sort
Spec <http://jsonapi.org/format/#fetching-sorting>.
Requests that the server sort the results in a given way:
$client->retrieve_all(
type => 'people',
sort => [qw/ age /], # sort by age, ascending
);
$client->retrieve_all(
type => 'people',
sort => [qw/ -age /], # sort by age, descending
);
Although not all endpoints will support this, it may be possible to sort by a
relationship's attribute:
$client->retrieve_all(
type => 'people',
sort => [qw/ -comments.created_date /],
);
filter
Spec <http://jsonapi.org/format/#fetching-filtering>.
This one is entirely dependent on the endpoint. It's usually employed to act as a
"WHERE" clause:
$client->retrieve_all(
type => 'people',
filter => {
id => [ 1, 2, 3, 4, 6 ], # IN ( 1, 2, ... )
age => 34, # age = 34
},
);
Sadly, more complex filters are currently not available.
retrieve
retrieve( type => $type, id => $id, %optional_arguments )
Similar to "retrieve_all", but retrieves a single resource.
retrieve_relationships
retrieve_relationships( type => $type, id => $id, rel_type => $rel_type, %optional_arguments )
Retrieves all of $id's relationships to $rel_type as resource identifiers; that is, as
hashrefs that contain only "type" and "id":
# retrieve_relationships(type=>'people', id=>2, rel_type=>'comments')
{
jsonapi => { version => "1.0" },
data => [
{ type => 'comments', id => 4 },
{ type => 'comments', id => 9 },
{ type => 'comments', id => 14 },
]
}
These two do roughly the same thing:
my $response = $client->retrieve( type => $type, id => $id );
my $relationships = $response->{data}{relationships}{$rel_type};
say join ", ", map $_->{id}, @$relationships;
my $response = $client->retrieve_relationships(
type => $type,
id => $id,
rel_type => $rel_type,
);
my $relationships = $response->{data};
say join ", ", map $_->{id}, @$relationships;
However, "retrieve_relationships" also allows you to page those relationships, which may
be quite useful.
Keep in mind that "retrieve_relationships" will return an arrayref for one-to-many
relationships, and a hashref for one-to-ones.
retrieve_by_relationship
retrieve_by_relationship( type => $type, id => $id, rel_type => $rel_type, %optional_arguments )
"retrieve_relationships" on steroids. It behaves the same way, but will retrieve full
resources, not just resource identifiers; because of this, you can also potentially apply
more complex filters and sorts.
create
create( type => $type, data => { ... }, id => $optional )
Create a resource of type $type using $data to populate it. Data must include the type,
and may include two other keys: "attributes" and "relationships":
$client->create(
type => 'comments',
data => {
type => 'comments',
attributes => { body => 'abc' },
relationships => {
author => { type => 'people', id => 55 },
liked_by => [
{ type => 'people', id => 55 },
{ type => 'people', id => 577 },
],
}
}
}
An optional "id" may be provided, in which case the server may choose to use it when
creating the new resource.
update
update( type => $type, id => $id, data => { ... } )
Can be used to update the resource. Data must have "type" and "id" keys:
$client->create(
type => 'comments',
id => 5,
data => {
type => 'comments',
id => 5,
attributes => { body => 'new body!' },
relationships => {
author => undef, # no author
liked_by => [
{ type => 'people', id => 79 },
],
}
}
}
An empty arrayref ("[]") can be used to clear one-to-many relationships, and "undef" to
clear one-to-one relationships.
A successful "update" will always return a response document; see the spec for more
details.
Spec <http://jsonapi.org/format/#crud-updating>.
delete
delete( type => $type, id => $id )
Deletes the resource.
update_relationships
update_relationships( type => $type, id => $id, rel_type => $rel_type, data => $data )
Update a resource's relationships. Basically a shortcut to using "update".
For one-to-one relationships, "data" can be either a single hashref, or undef. For one-
to-many relationships, "data" can be an arrayref; an empty arrayref means 'clear the
relationship'.
create_relationships
create_relationships( type => $type, id => $id, rel_type => $rel_type, data => [{ ... }] )
Adds to the specified one-to-many relationship.
delete_relationships
delete_relationships( type => $type, id => $id, rel_type => $rel_type, data => [{ ... }] )
Deletes from the specified one-to-many relationship.
Endpoint URI format
By default, "PONAPI::Client" assumes urls on the endpoint are in this format:
retrieve_all: /$type
retrieve: /$type/$id
retrieve_by_relationships: /$type/$id/$rel_type
retrieve_relationships: /$type/$id/relationships/$rel_type
create: /$type or /$type/$id
delete: /$type/$id
update: /$type/$id
update_relationships: /$type/$id/relationships/$rel_type
create_relationships: /$type/$id/relationships/$rel_type
delete_relationships: /$type/$id/relationships/$rel_type
# Will generate a request to /foo/99
$client->retrieve(
type => 'foo',
id => 99,
);
However, if another format is needed, two approaches are possible:
URI paths have a common prefix
If all the endpoint urls have a common prefix, ala "/v1/articles" instead of simply
"/articles", then you can just set "uri_base" as needed:
$client->retrieve(
type => 'foo',
id => 99,
uri_base => '/v1'
);
We can also set this when creating the client; if done this way, all requests generated
from this client will include the base:
my $new_client = PONAPI::Client->new(
uri_base => '/v1',
...
);
# This will generate a request to /v1/foo/99
$new_client->retrieve(
type => 'foo',
id => 99,
);
Completely different uris
If the endpoint's expected formats are wildly different, you can specify "uri_template"
with your request:
# Will generate a request to id_here_99_and_type_there/foo
$client->retrieve(
type => 'foo',
id => 99,
uri_template => 'id_here_{id}_and_type_there/{type}'
);
These placeholders are recognized:
• type
• id
• rel_type
This can only be done on a per-request basis.
AUTHORS
• Mickey Nasriachi <mickey@cpan.org>
• Stevan Little <stevan@cpan.org>
• Brian Fraser <hugmeir@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2019 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.