Welcome to eBay4R

eBay4R is a Ruby wrapper for eBay’s Web Services SOAP API (v449). Emphasis is on ease of use and small footprint.

Please report bugs and other problems, see “Author” section at the bottom.

Current releases and CVS snapshots can be downloaded from:

rubyforge.org/projects/ebay4r

Requirements

  • SOAP4R library newer than v1.5.5. At the time of this writing, the latest version was v1.5.5, which will not work. You have to get a snapshot that is dated 11-06-2005 or newer. You can find development snapshots here:

    dev.ctor.org/download

    So, for example, to download the 11-06-2005 snapshot (the one I personally used during development), go here:

    dev.ctor.org/download/archive/soap4r-20051106.tar.gz

    Note: I have seen one instance of SOAP4R v1.5.5 work out-of-the-box, and that was on a Ruby v1.8.3 source install on NetBSD 2.1. On my Debian 3.1 box, however, I had to install the newer snapshot. Go figure, I don’t know what the diff is…

Optionals

  • RubyGems

Installation

tar/gzip

Just unzip the archive anywhere you like, and see “Getting Started” below (you will need to add the ebay4r/lib path to your $RUBYLIB environment variable)

RubyGems

  • To install a gem you already downloaded:

    gem install ebay-<version>.gem
    
  • For the latest release with no fuss (previous download not required):

    gem install -r ebay
    

CVS

You can download the latest and greatest code using anonymous CVS, just type:

cvs -d :pserver:[email protected]:/var/cvs/ebay4r login
cvs -d :pserver:[email protected]:/var/cvs/ebay4r checkout ebay4r

Getting Started

If you installed eBay4R from a tarball or CVS, you will want to add the ebay4r/lib directory to your Ruby include path ($RUBYLIB). Then put

require 'eBayAPI'

at the top of your programs.

If you installed eBay4R with RubyGems, you don’t have to add anything to Ruby’s include path, just put

require 'rubygems'
require_gem 'ebay'

at the top of your programs.

Examples

Look at the examples/ directory. Edit the file myCredentials.rb and insert the appropriate values. Then you can run any of the example programs.

Hello, World!

The simplest eBay API call is “GeteBayOfficialTime”. Here’s how to call it with eBay4R:

require 'rubygems'
require_gem 'ebay'

# Put your credentials in this file
load('myCredentials.rb')

# Create new eBay caller object.  Omit last argument to use live platform.
eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)

resp = eBay.GeteBayOfficialTime

puts "Hello, World!"
puts "The eBay time is now: #{resp.timestamp}"

# Wasn't that easy?!

Adding an Item

This is a more complex example that performs a real (useful) function:

require 'rubygems'
require_gem 'ebay'

load('myCredentials.rb')

eBay = EBay::API.new($authToken, $devId, $appId, $certId, :sandbox => true)

# Notice how we nest hashes to mimic the XML structure of an AddItem request
resp = eBay.AddItem(:Item => { :PrimaryCategory => { :CategoryID => 57882 },
                               :Title => 'Mouse Pad',
                               :Description => 'A really cool mouse pad, you know you want it...',
                               :Location => 'On Earth',
                               :StartPrice => 12.0,
                               :Quantity => 1,
                               :ListingDuration => "Days_7",
                               :Country => "US",
                               :Currency => "USD",
                               :PaymentMethods => ["VisaMC", "PersonalCheck"] })

puts "New Item #" + resp.itemID + " added."

The way we nest hashes in the above AddItem() call may be confusing at first. It is just a short-hand way of creating the complex types we need for the call.

You may instead explicitly create the complex types (see “Creating Complex Data Types” below) needed for the call (it makes the code longer, but a bit more readable):

resp = eBay.AddItem(:Item => EBay.Item(:PrimaryCategory => EBay.Category(:CategoryID => 57882),
                                       :Title => 'Mouse Pad',
                                       :Description => 'A really cool mouse pad, you know you want it...',
                                       :Location => 'On Earth',
                                       :StartPrice => 12.0,
                                       :Quantity => 1,
                                       :ListingDuration => "Days_7",
                                       :Country => "US",
                                       :Currency => "USD",
                                       :PaymentMethods => ["VisaMC", "PersonalCheck"]))

Format of Requests

If eBay is your caller object, then you can issue any eBay API call by doing:

eBay.<call_name>( ... hash of named-arguments ... )

For example, to issue the GetItem call for Item ##4503432058 and return all information, you do:

eBay.GetItem(:DetailLevel => 'ReturnAll', :ItemID => '4503432058')

or to see your last invoice using the GetAccount call, you do:

eBay.GetAccount(:AccountHistorySelection => 'LastInvoice')

See the “eBay Web Services SOAP API Guide” for acceptable parameters and values for each API call. This guide can be downloaded at eBay’s SOAP Development Center.

Creating Complex Data Types

A number of elements in eBay’s schema are XML Schema simple types. For example, CategoryID, Title, and Description are all strings. But many elements, like Item and Seller, are of types “ItemType” and “SellerType”, respectively. These are complex data types, meaning they are structures composed of collections of simple types.

“How do I make a complex type object?”, you ask. Simple:

EBay.<element_name>( ... hash of named-arguments ... )

creates a new <element_name> element of type <element_name>Type. For example,

EBay.Item(:Title => 'Mouse Pad', :Description => '...')

creates a new ItemType object. Please note, these factory methods are class methods of module EBay, so the upper-case “E” in “EBay” is not a typo. A more common way to see this is:

EBay::Item( ... )

The only difference is if you do not pass any arguments to the factory method and do not explicitly put empty parentheses (), Ruby will assume it is a constant, not a method.

Setting XML Attributes

The symbol you use to set an XML attribute on an element is:

:xmlattr_<attribute_name>

For example, to create a <Label> element (corresponding to eBay’s LabelType) with an attribute of “visible” equal to “true”, you would do:

EBay.Label(:Name => "some string", :xmlattr_visible => true)

Format of Responses

There is a one-to-one correspondence between the XML returned by eBay and the way you access the values contained therein using the response object returned by the call. For example, let’s say you issued a “GetItem” call:

resp = eBay.GetItem(:DetailLevel => 'ReturnAll', :ItemID => '4503432058')

and eBay returned the following XML (abbreviated where appropriate):

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <soapenv:Body>
  <GetItemResponse xmlns="urn:ebay:apis:eBLBaseComponents">
   <Timestamp>2005-12-09T09:40:41.602Z</Timestamp>
   <Ack>Success</Ack>
   <Version>437</Version>
   <Build>e437_core_Bundled_2119808_R1</Build>
   <Item>
    ...

    <AutoPay>false</AutoPay>
    <BuyerProtection>ItemIneligible</BuyerProtection>
    <BuyItNowPrice currencyID="USD">0.0</BuyItNowPrice>
    <Country>US</Country>
    <Currency>USD</Currency>
    <Description>Fund. of Physics, 5th, by Halliday, Resnick, Walker</Description>
    <Escrow>None</Escrow>
    <GiftIcon>0</GiftIcon>
    ...

    <ShipToLocations>US</ShipToLocations>
    <ShipToLocations>CA</ShipToLocations>
   </Item>
  </GetItemResponse>
 </soapenv:Body>
</soapenv:Envelope>

The “resp” object is of type

SOAP::Mapping::Object

and contains all the XML elements between <GetItemResponse> ... </GetItemResponse>.

So, if you want to print the item description, just do:

puts resp.item.description

and you will see:

"Fund. of Physics, 5th, by Halliday, Resnick, Walker"

Repeated XML elements automatically become arrays of the same name, so to see all the locations this item can ship to, just do:

resp.item.shipToLocations.each { |loc| puts loc }

and you will see:

US
CA

It’s that easy! (Are any Java or C# developers reading this? Don’t be jealous… ;)

A Note about Case

Astute readers (all of you, right?) will notice that the first letter of every element contained within the response object is lower-case, even though in the XML it is upper-case. This is currently the way things are and you will have to remember to lower the first character in your code.

Ruby’s convention is that only classes, modules, and constants begin with upper-case letters. The author of the SOAP4R library (which contains wsdl2ruby.rb) respected this convention, and as a result, the eBay.rb file I use (generated from eBay’s WSDL) has this mapping.

I haven’t come up with any Ruby magic to dynamically allow upper-case first characters to work also, so if you happen to want to take a crack at it and get it working, please send me your patches (see “Author” section at the bottom).

Please note, the opposite does not apply. That is, you can submit a call using either case of the first character, and your arguments can also have either case letter first. For example, this:

resp = eBay.GetItem(:DetailLevel => 'ReturnAll', :ItemID => '4503432058')

is the same as:

resp = eBay.getItem(:detailLevel => 'ReturnAll', :itemID => '4503432058')

Debugging

If “eBay” is your eBay caller object, as in:

eBay = EBay::API.new( ... )

You can see XML wiredumps by doing:

eBay.debug = true

before you issue any eBay API calls. This is useful to see the raw XML of what eBay is sending back to you.

Files

examples/

Examples of eBay API calls using this library. You will want to check out
these examples before making your own calls.

lib/eBayAPI.rb

The heart of this library

lib/eBayDriver.rb

Autogenerated by wsdl2ruby.rb

lib/eBay.rb

Autogenerated by wsdl2ruby.rb

lib/RequesterCredentialsHandler.rb

Helper for generating the eBay Authentication header for each call

test/

Unit and functional tests

To Do

  • Add many more examples

  • Add more unit and functional tests

Author

Garry C. Dolley

gdolley [at] ucla.edu

AIM: garry97531

Copyright © 2005,2006 Garry C. Dolley

eBay4R is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

eBay4R is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with eBay4R; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

$Id: README,v 1.17 2006/05/11 02:34:44 garrydolley Exp $