/ 
Net-PMP-0.006
River stage one • 1 direct dependent • 1 total dependent
/ Net::PMP::Client

NAME

Net::PMP::Client - Perl client for the Public Media Platform

SYNOPSIS

use Net::PMP::Client;

my $host = 'https://api-sandbox.pmp.io';
my $client_id = 'i-am-a-client';
my $client_secret = 'i-am-a-secret';

# instantiate a client
my $client = Net::PMP::Client->new(
    host   => $host,
    id     => $client_id,
    secret => $client_secret,
); 

# authenticate
my $token = $client->get_token();
if ($token->expires_in() < 10) {
    die "Access token expires too soon. Not enough time to make a request. Mayday, mayday!";
}
printf("PMP token is: %s\n, $token->as_string());

# search
my $search_results = $client->search({ tag => 'samplecontent', profile => 'story' });  
my $results = $search_results->get_items();
printf( "total: %s\n", $results->total );
while ( my $r = $results->next ) { 
    printf( '%s: %s [%s]', $results->count, $r->get_uri, $r->get_title, ) );
}

DESCRIPTION

Net::PMP::Client is a Perl client for the Public Media Platform API (http://docs.pmp.io/).

METHODS

new( args )

Instantiate a Client object. args may consist of:

host

Default is https://api-sandbox.pmp.io.

id (required)

The client id. See https://github.com/publicmediaplatform/pmpdocs/wiki/Authenticating-with-the-API#generating-credentials.

secret (required)

The client secret. See https://github.com/publicmediaplatform/pmpdocs/wiki/Authenticating-with-the-API#generating-credentials.

debug

Boolean. Default is off.

ua

A LWP::UserAgent object.

pmp_content_type

Defaults to application/vnd.collection.doc+json. Change at your peril.

BUILD

Internal method for object construction.

last_response

Returns the most recent HTTP::Response object. Useful for debugging client behaviour.

get_home_doc

Returns the CollectionDoc for the API root. This object is cached for performance reasons.

get_token([refresh],[warning_ttl])

Returns a Net::PMP::AuthToken object. The optional refresh boolean indicates that the Client should ignore any cached token and fetch a fresh one.

If get_home_doc() is undefined (i.e., no initial access has been attempted), then this method will return undef.

If the token will expire in less than warning_ttl seconds, the client will sleep() that long and then refresh itself. The default is 10 seconds.

revoke_token

Expires the currently active AuthToken.

get_credentials_uri

Returns the URI for the Credentials API.

create_credentials( params )

Instantiates credentials at server. params should be a hash of key/value pairs.

username (required)
password (required)
scope (default: read)
expires (default: 86400)
label (default: null)

Returns a Net::PMP::Credentials object.

delete_credentials( params )

Deletes credentials at the server.

params should consist of:

username
password
client_id

uri_for_doc(guid)

Returns full URI for guid.

uri_for_profile(profile)

Returns full URI for profile.

uri_for_schema(schema)

Returns full URI for schema.

get(uri)

Issues a GET request on uri and decodes the JSON response into a Perl scalar.

If the GET request returns a 404 (Not Found) will return 0 (zero).

If the GET request returns anything other than 200, will croak.

If the GET request returns 200, will return the JSON response, decoded.

Retrieves the base doc edit link object for the API.

put(doc_object)

Write doc_object to the server. doc_object should be an instance of Net::PMP::CollectionDoc.

Returns the JSON response from the server on success, croaks on failure.

Normally you should use save() instead of put() directly, since save() optionally validates the doc_object before calling put() and makes sure there is a guid and href defined.

delete(doc_object)

Remove doc_object from the server. Returns true on success, croaks on failure.

get_doc( [uri] [,tries] )

Returns a Net::PMP::CollectionDoc representing uri. Defaults to the API base endpoint if uri is omitted or false.

If uri is not found, returns 0 (zero) just like get().

The second, optional parameter tries indicates how many re-tries should be attempted when the response is a 404. This feature helps compenstate for occasional latency on the server between an initial save and subsequent read, since PUT and DELETE requests always return a 202 (accepted but not necessarily acted upon). The default is 1 try.

get_doc_by_guid(guid)

Like get_doc() but takes a guid as argument.

search( opts [,tries] )

Search in the 'urn:collectiondoc:query:docs' namespace.

Returns a Net::PMP::CollectionDoc object for opts. opts are passed directly to the query link URI template. See https://github.com/publicmediaplatform/pmpdocs/wiki/Query-Link-Relation.

The second, optional parameter tries is passed internally to get_doc(). See the description of get_doc().

save(doc_object)

Write doc_object to the server. doc_object may be a Net::PMP::Profile object, in which case the as_doc() method is called on it, or it may be a Net::PMP::CollectionDoc object.

Returns a Net::PMP::CollectionDoc object with its URI updated to reflect the server response.

AUTHOR

Peter Karman, <karman at cpan.org>

BUGS

Please report any bugs or feature requests to bug-net-pmp at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-PMP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::PMP::Client

You can also look for information at:

ACKNOWLEDGEMENTS

American Public Media and the Public Media Platform sponsored the development of this module.

LICENSE AND COPYRIGHT

Copyright 2013 American Public Media Group

See the LICENSE file that accompanies this module.