NAME

Ipernity::API - Perl interface to the Ipernity API

SYNOPSIS

        use Ipernity::API;
        
        my $api = Ipernity::API->new(

                'api_key'       => '12345678901234567890123456789012',
                'secret'        => '0123456789012345',
                'outputformat'  => 'xml',

        );

        my $raw_response = $api->execute(

                'method'        => 'test.hello',

        );

        my $hash = $api->execute_hash(

                'method'        => 'test.hello',
                'auth_token'    => '12345-123-1234567890',

        );
        
        my $frob = $api->fetchfrob();

        my $authurl = $api->authurl(

                'frob'          => $frob,
                'perms'         => {

                        'perm_doc'      => 'read',
                        'perm_network'  => 'write',
                        'perm_blog'     => 'delete',

                },

        );

        my $token = $api->authtoken( $frob );

        ### After fetching the authtoken, all useful user information are
        ### stored in the $api->{ 'auth' } section for later usage

        my $username  = $api->{ 'auth' }->{ 'username' };
        my $user_id   = $api->{ 'auth' }->{ 'userid' };
        my $realname  = $api->{ 'auth' }->{ 'realname' };
        my $authtoken = $api->{ 'auth' }->{ 'authtoken' };

DESCRIPTION

Ipernity::API is a full implementation of the Ipernity API interface. It uses LWP::UserAgent to communicate with the API and returns the results in the 3 possible formats (provided by Ipernity): JSON, XML, SOAP, XML-RPC

METHODS

new( configuration arguments )

The constructor takes a single arguments with all needed configuration values. api_key and secret are mandatory values. The outputformat is optional and will be set to XML if not defined.

fetchfrob()

This method fetches a frob from Ipernity, which later can be used to generate and authentication URL and an AuthToken

authurl( config arguments )

Generates an authentication URL which can be provided to the user. This is needed so that the user can confirm that he grants permissions to the script. This method requires a frob and a perms parameter to be set.

authtoken( frob )

Will fetch the AuthToken from Ipernity for later usage (for authenticated API calls). This method requires a valid frob to be provided as argument.

execute( ipernity parameters )

Calling this method will execute the provided method together with its options on the Ipernity API. As result the method returns the raw answer from the API so that the script can take care of parsing the output from Ipernity on its own

execute_hash( ipernity parameters )

Works similar to execute() but returns a hashref for easy access to the results from Ipernity

CAVEATS

Since version 0.07 the execute_hash() function always returns arrays, even if the XML result would be only one. Please not that you might have to adjust your code, in case you are upgradeing to v0.07 (which is highly recommended).

Starting with verseion 0.09 the new() constructor doesn't accept a hashref of configuration parameters anymore, but will now require the single key/value pairs provided to the constructor directly. If you are upgrading to 0.09 you will have to adjust your code, so that will with work with newer setup.

DEVELOPMENT

The latest (development) version of Ipernity::API is always available via GIT at: http://nop.li/ipernityapi

AUTHOR

Winfried Neessen, <doomy@dokuleser.org<gt>

REQUIRES

Perl 5, URI, HTTP::Request, XML::Simple, LWP::UserAgent, Digest::MD5

BUGS

Please report bugs in the CPAN bug tracker.

COPYRIGHT

Copyright (c) 2008-2010, Winfried Neessen <doomy@dokuleser.org> All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the neessen.net nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.