Object::eBay(3p)

NAME
Object::eBay - Object-oriented interface to the eBay API

SYNOPSIS
    use Object::eBay;
    my $ebay = # ... create a Net::eBay object ...
    Object::eBay->init($ebay);

    my $item = Object::eBay::Item->new({ item_id => 12345678 });
    my $title = $item->title();
    my $price = $item->selling_status->current_price();
    print "Item titled '$title' is going for $price\n"

DESCRIPTION
Object::eBay provides an object-oriented interface to the eBay API. Objects are created to represent entities dealing with eBay such as items, users, etc. You won't want to create objects of the class Object::eBay but rather of its subclasses such as: Object::eBay::Item or Object::eBay::User. eBay API calls are processed using the Perl module Net::eBay (available from CPAN or from <http://www.net-ebay.org>).

Object::eBay follows some simple rules to make the names of eBay API objects more "Perlish." Namely, for packages, eBay's camelcase is retained. For example Object::eBay::ListingDetails. For attribute names, the camelcase is converted to underscore separated method names with roughly the following algorithm:

    Before each capital letter after the first one, place an underscore
    Make all letters lowercase

So, eBay's "FeedbackScore" becomes the method name "feedback_score". Generally, the transformation algorithm does what you'd expect. Attributes like "ItemID" become "item_id" as anticipated.

PUBLIC METHODS
The following methods are intended for general use.

  init
  Object::eBay->init($net_ebay_object);

Requires a single Net::eBay object as an argument. This class method must be called before creating any Object::eBay objects. The Net::eBay object provided to "init" should be initialized and ready to perform eBay API calls. All Object::eBay objects will use this Net::eBay object.

  new
This documentation covers functionality that is common to the "new" method of all Object::eBay classes. For details for specific class, see the appropriate class documentation. The "new" constructor tries to be as lazy as possible and will not invoke an eBay API call until it's really necessary. Generally this happens when the first method is invoked on a new object. After that, cached values from the API call are returned. That means, each object should only cost use API call and that only if you call a method on the object.

The "new" method constructs a new object. It accepts a single hashref as an argument. Each subclass determines the values that are accepted or required. However, "new" always accepts a key named 'needs_methods' to indicate which expensive methods you plan to use. The value of this key should be an arrayref containing the names of the expensive methods you intend to call with the newly created object.

Some eBay API calls return a lot of data, for example, the description of an item can be quite large. To avoid a performance penalty for programs that don't use these expensive methods, Object::eBay avoids fetching the data unless you really need it. You indicate to Object::eBay that you plan to use an expensive method by specifying it with the 'needs_methods' argument. Here's an example where we intend to access an item's description:

    my $item = Object::eBay::Item->new({
        item_id       => 123456789,
        needs_methods => [qw( description )],
    });

Expensive methods indicate this in their documention so that you know in advance. Take a look at "description" in Object::eBay::Item for example.

PRIVATE METHODS
The following methods are intended for internal use, but are documented here to make code maintenance and subclassing easier. Most users of Object::eBay will never use these methods. Instead, proceed to the documentation about the other Object::eBay classes: "SEE ALSO".

  api_inputs
    $res = Object::eBay->ask_ebay(
        $self->api_call(),
        $self->api_inputs(),
    );

This method returns a hash reference containing all the inputs required by the invocant's API call. This is used when retrieving the details about an object which does not yet have any details.

  ask_ebay
    $res = Object::eBay->ask_ebay(
        GetItem => {
            ItemID => 12345678,
            DetailLevel => 'ItemReturnDescription',
        }
    )

A thin wrapper around "submitRequest" in Net::eBay which performs API calls using eBay's API and encapsulates error handling. If an error occurs during the API call, or eBay returns a result with an error, an exception is thrown.

  complex_attributes
    __PACKAGE__->complex_attributes({
        Seller => {
            class => 'User',
        },
        Description => {
            DetailLevel => 'ItemReturnDescription',
        },
        WatchCount => {
            IncludeWatchCount => 'true',
        },
    });

This method is called by subclasses of eBay::Object to create methods that map to attributes of eBay API return values. The example above will create three methods: "seller", "description" and "watch_count". The return value of the "seller" method will be an Object::eBay::User object. The return value of the "description" and "watch_count" methods will be non-reference scalars.

The "description" method requires that 'DetailLevel' be 'ItemReturnDescription' or higher. In addition to 'DetailLevel', any API Input value can be specified (for example 'IncludeWatchCount' in the sample above). Object::eBay objects try to be lazy and request as little information from eBay as possible. This is done by correlating arguments to "complex_attributes" with the value of 'needs_methods' set when calling "new".

The argument to "complex_attributes" should be a single hash reference. The keys of the hash should be eBay attribute names. The value of each key should likewise be a hash reference.

For simpler mapping of eBay attributes to method names, see "simple_attributes".

  ebay_name_to_method_name
    $method_name = Object::eBay->ebay_name_to_method_name('SellingStatus')
    # returns 'selling_status'

Converts an eBay name in camelcase to a method name in lowercase with words separated by underscores. This method implements the algorithm sketched in the "DESCRIPTION" section.

  get_details
    $title = $item->get_details->{Title};

Returns a hash reference containing detailed information about the invocant object. This hash reference is a slightly modified version of the hashref returned by Net::eBay::submitRequest. Again, this method is intended to be private. If you want to access information about an Object::eBay object, please use an accessor method. If there is no accessor method for the information you want, see "HELPING OUT" for information on how to add the accessor method and then send me a patch.

  method_name_to_ebay_name
    $ebay_name = Object::eBay->method_name_to_ebay_name('selling_status')
    # returns 'SellingStatus'

Converts a method name with underscores separating words into an ebay name in camelcase. This method implements the inverse of the algorithm sketched in the "DESCRIPTION" section.

  simple_attributes
    __PACKAGE__->simple_attributes(qw{ Quantity Title });

This method is called by subclasses of eBay::Object to create methods that map easily to attributes of eBay API return values. The example above will create two methods: "quantity" and "title" which return the "Quantity" and "Title" attributes of the object in question. The return value of methods created with "simple_attributes" will be non-reference scalars. For more complex mapping of eBay attributes to method names, see "complex_attributes".

DIAGNOSTICS

  init() requires a valid Net::eBay object
This exception is thrown when "init" is called without providing a Net::eBay object as the argument.

  Error inflating '%s': %s
If calling the inflation subroutine defined by a Object::eBay subclass causes an exception, this exception will be thrown with the original exception message attached.

  Can't find '%s' via %s
If the API response from eBay does not contain the raw information necessary to evaluate a method, this exception is thrown.

  Can't inflate '%s' via %s
The result of inflating an attribute into an object was an undefined value.

CONFIGURATION AND ENVIRONMENT
Object::eBay requires no configuration files or environment variables. However, Net::eBay can make use of configuration files and that is often easier than including set up information in every program that uses Object::eBay.

DEPENDENCIES

•   Class::Std

•   Net::eBay

INCOMPATIBILITIES
None known.

HELPING OUT
The latest source code for Object-eBay is available with git from <git://ndrix.com/Object-eBay>. You may also browse the repository at <http://git.ndrix.com/?p=Object-eBay;a=summary>.

If you have any patches, please submit them through the RT bug tracking interface see "BUGS AND LIMITATIONS". Right now, the most needed assistance is with filling out the objects and associated accessor methods. To create a new Object::eBay subclass to implement an additional class of objects on eBay, you'll need to implement the following methods. Take a look at Object::eBay::Item for examples.

  api_call
Override this method so that it returns the name of the eBay API call which should be invoked to return details about a particular object. For example, the Object::eBay::Item class defines this method to return "GetItem"

  response_field
Override this method so that it returns the hash key which accesses all the important details about a particular object. For example, the Object::eBay::Item class defines this method to return "Item".

BUGS AND LIMITATIONS
Please report any bugs or feature requests to "bug-object-ebay at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Object-eBay>. 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 Object::eBay

You can also look for information at:

•   GitHub

    <http://github.com/mndrix/Object-eBay>

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/Object-eBay>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/Object-eBay>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Object-eBay>

•   Search CPAN

    <http://search.cpan.org/dist/Object-eBay>

•   Paid Support and Development

    <http://www.ndrix.com>

SEE ALSO

•   Object::eBay::Item

•   Object::eBay::ListingDetails

•   Object::eBay::SellingStatus

•   Object::eBay::User

ACKNOWLEDGEMENTS
JJ Games for sponsoring the original development <http://www.jjgames.com>.

Video Game Price Charts for sponsoring further development <http://www.videogamepricecharts.com>.

Igor Chudov for writing Net::eBay.

AUTHOR
Michael Hendricks <michael@ndrix.com>

LICENSE AND COPYRIGHT
Copyright (c) 2006-2007 Michael Hendricks (<michael@ndrix.com>). All rights reserved.

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