/ 
WWW-FreshBooks-API-0.1.0
River stage zero No dependents
/ WWW::FreshBooks::API

NAME

WWW::FreshBooks::API - Perl Interface to the Freshbooks 2.1 API!

VERSION

Version 0.1.0

SYNOPSIS

    use WWW::FreshBooks::API;

    my $fb = WWW::FreshBooks::API->new({
		svc_url => "https://sample.freshbooks.com/api/xml-in",
		auth_token => "yourfreshbooksapiauthenticationtoken",
	});

	# old n' busted - though still works for backward compatibility
	# ---------------------------------------------------------------
	    # $ref is a hash reference created from the xml response.
	    # $resp is an HTTP::Response object containg the response.
    my ($ref,$resp) = $fb->call('client.list', {
		$arg1 => 'val1',
		$arg2 => 'val2',
	});

    # Verifies that the request was completed successfully.
    # Displays the client_id of the first client in the list.
    if ($ref) {
        $ref->{'client'}[0]->{'client_id'};
    }

    # Displays the response content as a string
    $resp->as_string;
	# ---------------------------------------------------------------


	# new hotness - better data handling, easier access to response data, etc.
	# ----------------------------------------------------------------
		# result and response data now accessed via class accessors.
	$fb->call("client.list", {foo => "bar", biz => "baz"});
	my $response = $fb->response;
	unless ($response->status eq "ok") {
		return;
	}

	my $results = $fb->results;
	$results->total;		# Total number of result items
	$results->items;		# array of results as result item classes
	$results->item_fields;	# hash of result item field names keyed by class - used to create item class accessors
	$results->item_class;	# name of the class created from the result items
	$results->iterator; 	# iterator for list of result items

	my $items = $results->iterator;
	my $fields = $results->item_fields->{$results->item_class};
	while (my $item = $items->next()) {
		$item->client_id;
		$item->organization;

		# or something like ..

		map { print $_ . " --> " . $item->$_ . "\n" } @{$fields};
	}
	# -----------------------------------------------------------------

DESCRIPTION

The long awaited update to the original perl freshbooks api interface adds some much needed data handling improvements, on-the-fly response item class creation, and a simple result item iterator for improved handling of result lists. Stubs of the original implementation exist for backwards compatibility, and access to new features are possible without changing old code.

The result item classes are built on the fly using the data contained within the response. This is meant to keep class accessors up to date in the absence of a provided service description and without having to maintain your own. Example of how this works:

# your "client.list" request returns:
 <?xml version="1.0" encoding="utf-8"?>  
 <response status="ok">  
   <clients page="1" per_page="15" pages="3" total="42">  
     <client>  
       <client_id>13</client_id>  
       <organization>ABC Corp</organization>  
       <username>janedoe</username>  
       <first_name>Jane</first_name>  
       <last_name>Doe</last_name>  
       <email>janedoe@freshbooks.com</email>  
     </client>  
     ...  
   </clients>  
 </response>

# on the fly we create WWW::FreshBooks::API::Client with accessors available via:
my $item = $results->iterator->next();
$item->client_id;		# 13
$item->organization; 	# ABC Corp
$item->username;		# janedoe
....

WARNING

Please note that "item" refers to each object returned in the list of results. This is not to be confused with a Freshbooks line item. I realize that this is a bit semantically unsound, but I have to point the finger at the FB kats for this one. I mean "item" is pretty vague for a top level api, no? My vocab-fu is not strong ... plus, by the time I noticed the collision, I was married to the item reference.

FUNCTIONS

new
init
call

RESPONSE CLASS ACCESSORS

$response-http>
$response-ref>
$response-content>
$response-as_string>
$response-status>

RESULT CLASS ACCSSORS

$results-page>
$results-per_page>
$results-pages>
$results-total>
$results-fields>
$results-items>
$results-iterator>

DEPENDENCIES

Class::Accessor::Children Iterator::Simple LWP::UserAgent XML::Simple

AUTHOR

Anthony Decena, <anthony at mindelusions.com>

BUGS

Please report any bugs or feature requests to bug-www-freshbooks-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-FreshBooks-API. 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 WWW::FreshBooks::API

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2009 Anthony Decena, all rights reserved.

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