Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  WEBSERVICE::ISBNDB::API (3)

.ds Aq ’


WebService::ISBNDB::API - Base class for the WebService::ISBNDB API classes



    require WebService::ISBNDB::API;

    $handle = WebService::ISBNDB::API->new({ protocol => REST =>
                                      api_key => $key });

    $book = $handle->new(Books => { isbn => 0596002068 });
    $all_lotr = $handle->search(Books =>
                                { title => lord of the rings  });


The <B>WebService::ISBNDB::APIB> class is the base for the classes that handle books, publishers, authors, categories and subjects. It also acts as a factory-class for instantiating those other classes. Any of the data classes can be created from the constructor of this class, using the syntax described below.

This class manages the common elements of the data classes, including the handling of the communication agent used to make requests of <B>isbndb.comB>. This class (and all sub-classes of it) are based on the <B>Class::StdB> inside-out objects pattern. See Class::Std for more detail.

All error conditions in the methods of this class are handled using the exception model provided by the <B>ErrorB> module. Most errors are thrown in the form of <B>Error::SimpleB> exception objects. See Error for more detail.


In order to access the <B>isbndb.comB> web service programmatically, you must first register an account on their site (see <>) and then create an access key. You can create more than one key, as needed. All the API calls require the access key be part of the parameters.

More information is available at <>. You can also view the documentation for their API at <>.


The following methods are provided by this class, usable by all derived classes. Private methods are not documented here.


The constructor for this class behaves a little differently than the default constructor provided by <B>Class::StdB>.
new([ $TYPE, ] $ARGS) Constructs a new object, returning the referent. The value of $ARGS is a hash-reference of key/value pairs that correspond to the attributes for the class. If $TYPE is provided, then the value must match one of the known data-types, and the new object will be created from that class rather than <B>WebService::ISBNDB::APIB>. Likewise, $ARGS will be passed to that class’ constructor and not processed at all by this one.

If $TYPE is not a known type (see Managing Types), then an exception of type <B>Error::SimpleB> is thrown.

The class also defines:
copy($TARGET) Copies the target object into the calling object. All attributes (including the ID) are copied. This method is marked CUMULATIVE (see Class::Std), and any sub-class of this class should provide their own copy() and also mark it CUMULATIVE, to ensure that all attributes at all levels are copied.
This method copies only the basic attributes. Each of the implementation classes must provide additional copy() methods (also marked CUMULATIVE) to ensure that all attributes are copied.


The accessor methods are used to set and retrieve the attributes (instance data) stored on the object. While a few of them have special behavior, most operate as simple get or set accessors as described in Class::Std. The attributes for this class are:
protocol This attribute identifies the communication protocol this object will use for making requests of the <B>isbndb.comB> service. The value for it is always forced to upper-case, as all protocols are regarded in that manner.
(See Default Attribute Values.)
api_key To use the <B>isbndb.comB> service, you must register on their web site and obtain an API key. The key must be used on all data requests to their API. This attribute stores the API key to be used on all requests made by the object. (See Default Attribute Values.)
agent This attribute stores the object used for communicating with the service. The value must be a sub-class of the <B>WebService::ISBNDB::AgentB> class.
(See Default Attribute Values.)
agent_args When the <B>WebService::ISBNDB::AgentB>-based object is instantiated, any arguments stored in this attribute will be passed to the constructor. If set, this attribute’s value must be a hash-reference (otherwise the constructor will throw an exception). (See Default Attribute Values.)
type This attribute is read-only by users that are not sub-classes of this class. It identifies the class-type of the object, which is generally the last element of the class name (API, Books, etc.). It allows the <B>WebService::ISBNDB::AgentB> sub-classes to make choices based on the type of the object. (Type in this context should not be confused with types as they pertain to mapping books, publishers, etc. to specific data classes.)
The following accessor methods are provided by this class:
get_protocol Retrieve the current value of the protocol attribute.
set_protocol($PROTO [ , $AGENT ]) Set the protocol to use for communication. Optionally, you can also provide an agent instance at the same time, and set both values. If an agent is specified, it will be tested against the new protocol value, to make sure it works with that protocol. If the agent does not match the protocol, an exception will be thrown.
get_api_key Retrieve the current API key.
set_api_key Set the API key to use when contacting the service. If this value is not recognized by the <B>isbndb.comB> service, you will not be able to retrieve any data.
get_agent Retrieve the current <B>WebService::ISBNDB::AgentB>-derived object used for communication. Unless the agent was explicitly provided as an argument to the constructor, the agent object is constructed lazily: it is only instantiated upon the first call to this method.
set_agent Set a new agent object for use when this object makes requests from the service. An agent object must derive from the <B>WebService::ISBNDB::AgentB> class (that class itself cannot act as an agent). When a new agent is assigned, its <B>protocolB> method is called with the current value of the protocol attribute of the object, to ensure that the agent matches the protocol. If not, an exception is thrown.
get_agent_args Get the arguments that are to be passed to agent-instantiation.
set_agent_args Provide a new set of arguments to be used when instantiating an agent object. The value must be a hash reference, or the constructor for the agent class will thrown an exception.
get_type Get the class’ type. In most cases, this is the last component of the class name. Note that there is no set-accessor for this attribute; it cannot be set by outside users.

    Default Attribute Values

In addition to the above, the following accessors are provided to allow users to set default values for the protocol, the API key, the agent and the defaut arguments for agent construction. This allows you to set these once, at the start of the application, and not have to pass them to every new object instantiation:
set_default_protocol($PROTO) Sets the default protocol to the value of $PROTO. Unlike the API key, there is already a default value for this when the module is loaded (<B>RESTB>).
get_default_protocol Returns the current default protocol.
set_default_api_key($KEY) Sets a new default API key. There is no built-in default for this, so you must either call this, set it via module-import (see below), or provide the key value for each individual object creation.
get_default_api_key Returns the current default API key.
set_default_agent($AGENT) Sets a new value for the default agent. Any object created without an agent attribute will inherit this value. The value must be an instance of <B>LWP::UserAgentB> or a derivative class.
get_default_agent Get the default agent. If it hasn’t been set the first time this is called, one is created (possibly using the default agent arguments).
set_default_agent_args($ARGS) Sets a new value for the default arguments to agent creation. Any time an agent is created without the object having an explicit value for arguments to pass, this value is read and used. The value must be a hash reference.
get_default_agent_args Get the set of default agent arguments, if any.
Besides using these accessors to provide the defaults, you can also specify them when loading the module:

    use WebService::ISBNDB::API (api_key => abc123);

agent, agent_args, api_key and protocol are recognized at use-time.

    Managing Types

As the root of the data-class hierarchy, this package also provides the methods for managing the data-types known to the overall module.

The built-in data-types are:
Authors This type covers the author data structures returned by <B>isbndb.comB>. It is covered in detail in WebService::ISBNDB::API::Authors. =item Books

This type covers the book data structures returned by <B>isbndb.comB>. It is covered in detail in WebService::ISBNDB::API::Books.

Categories This type covers the category data structures returned by <B>isbndb.comB>. It is covered in detail in WebService::ISBNDB::API::Categories.
Publishers This type covers the publisher data structures returned by <B>isbndb.comB>. It is covered in detail in WebService::ISBNDB::API::Publishers.
Subjects This type covers the subject data structures returned by <B>isbndb.comB>. It is covered in detail in WebService::ISBNDB::API::Subjects.
Note that the types are case-sensitive.

The following methods operate on the internal types map:
add_type($TYPE, $CLASS) Add a mapping for the type specified by $TYPE to the class specified in $CLASS. $TYPE may be one of the core types listed above; if so, then the new class will override the built-in class for that type. You cannot remove a type/class mapping for any of the core types; you can only re-override them by calling the method again. If you want to temporarily redirect a type, you must save the original value (using <B>class_for_typeB>) and manually restore it by called <B>add_typeB> again.
class_for_type($TYPE) Returns the class-name for the given $TYPE. Throws an exception if $TYPE is not in the mapping table.
remove_type($TYPE) Removes the type/class mapping for the given $TYPE. Note that you cannot remove the mappings for any of the core types listed above, even if you have already overridden them with <B>add_typeB>. If you pass any of the core types, an exception will be thrown.
All of the type-map methods may be called as static methods.

    Retrieving Data

<B>WebService::ISBNDB::APIB> and its sub-classes support the retrieval of data in two ways: single-record and searching.

Single-record retrieval is for getting just one result from the service, usually from a known unique key (such as fetching a book by the ISBN). The interface for it always returns a single result, even when the criteria are not specific-enough and more than one record is returned. In these cases, the first record is used and the rest discarded.

Searching returns zero or more results from a search of the service using the provided criteria. Presently, the return is in the form of a list-reference (even when the result-set has only one element or no elements). This will change in the future, to an object-base result-set that offers iterators and delayed-loading of results.

The data-retrieving methods are:
find($TYPE, $IDENT|$ARGS) Finds a single record, using either a scalar identifying value ($IDENT) or a hash reference ($ARGS) with one or more key/value pairs. The value of $TYPE tells WebService::ISBNDB::API) which data class to do the find-operation on. If the value is not a known type, an exception is thrown.

How the scalar value $IDENT is used in the data-retrieval is dependent on the value of $TYPE. See the documentation for the various data classes for more detail.

search($TYPE, $ARGS) Search for items of type $TYPE using the key/value pairs in the hash reference $ARGS. $ARGS must be a hash reference, there is no corner-case for a scalar as with <B>findB>.
normalize_args($ARGS) In this class, this method does nothing. It is available for sub-classes to overload. If a class overloads it, the requirement is that any changes to the arguments be made in-place, altering $ARGS, and that the return value be either $ARGS itself or a copy.

The purpose of this method is to allow implementation classes to make any translation of user-space argument names to the names used by <B>isbndb.comB>. Most of the implementation classes also use it to add more arguments in order to retrieve extra data from the service.

These methods may be called as static methods.


The data returned by this class is only as accurate as the data retrieved from <B>isbndb.comB>.

The list of results from calling search() is currently limited to 10 items. This limit will be removed in an upcoming release, when iterators are implemented.


Class::Std, Error, WebService::ISBNDB::Agent, WebService::ISBNDB::API::Authors, WebService::ISBNDB::API::Books, WebService::ISBNDB::API::Categories, WebService::ISBNDB::API::Publishers, WebService::ISBNDB::API::Subjects


Randy J. Ray <>


This module and the code within are released under the terms of the Artistic License 2.0 ( This code may be redistributed under either the Artistic License or the GNU Lesser General Public License (LGPL) version 2.1 (
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 WEBSERVICE::ISBNDB::API (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.