NAME

WebService::Technorati::ApiQuery - a base class for web services client queries

SYNOPSIS

This class has no constructor, as there's little use instantiating one. The fun is in the derived classes.

DESCRIPTION

When adding a new API call client, this class provides a lot scaffolding such as query string building, HTTP protocol stuff, XML::XPath object creation, and other common behaviors.

USAGE

This class is mostly utility functions that are inherited by ApiQuery derivations.

BUGS

No bugs currently open

SUPPORT

Join the Technorati developers mailing list at http://mail.technorati.com/mailman/listinfo/developers

AUTHOR

    Ian Kallen
    ikallen _at_ technorati.com
    http://developers.technorati.com

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the following Creative Commons License: http://creativecommons.org/licenses/by/2.0 as well as the indemnification provisions of the Apache 2.0 style license, the full text of which can be found in the LICENSE file included with this module.

 Usage     : apiHostUrl('http://developers.technorati.com')
 Purpose   : gets/sets the base URL
 Returns   : a URL string
 Argument  : a base URL, if setting the value; otherwise none
 Throws    : none
 Comments  : Instantiations of an ApiQuery subclass may want to change 
             which api host they connect to (i.e. for beta testing 
             interface changes that aren't yet deployed to the default 
             host, http://api.technorati.com).
See Also   : WebService::Technorati

fetch_url

 Usage     : fetch_url('http://developers.technorati.com')
 Purpose   : fetches the URL contents
 Returns   : a scalar of the content data
 Argument  : a URL
 Throws    : WebService::Technorati::NetworkException if the URL contents
             cannot be fetched
 Comments  : the underlying implementation uses LWP::UserAgent
See Also   : WebService::Technorati

build_query_string

 Usage     : build_query_string($hashref);
 Purpose   : transforms the keys/values into a query string
 Returns   : the query string
 Argument  : a hash reference
 Throws    : none
 Comments  : multi value keys are not yet accounted for
See Also   : WebService::Technorati

execute

 Usage     : build_query_string($apiurl, $hashref);
 Purpose   : handles the low level execution cycle of an API call
 Returns   : void
 Argument  : a hash reference
 Throws    : none
 Comments  : calls build_query_string, fetch_url, instantiates XML::XPath 
             and calls readResults
See Also   : WebService::Technorati

readResults

 Usage     : readResults($xpath_data);
 Purpose   : this is an abstract method
 Returns   : void
 Argument  : an XML::XPath representation of an API response
 Throws    : WebService::Technorati::MethodNotImplementedException if not overriden
 Comments  : derived classes must implement this in order to use execute(...)
See Also   : WebService::Technorati