Welcome to eBay4R

:Author: Garry Dolley :Date: 03-28-2008 :Version: v1.1 :eBay API: 555

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

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

Current release can be downloaded from:

rubyforge.org/projects/ebay4r

The latest code is in the following Git repository:

git://github.com/up_the_irons/ebay4r.git

Requirements

  • SOAP4R library v1.5.7 or newer. The specific version I’m using for testing is soap4r-1.5.7.90.20070921.

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

Git ~~~

You can download the latest and greatest code using Git, just type

git clone git://github.com/up_the_irons/ebay4r.git

Important Note about Using eBay4R and Ruby on Rails

If you installed SOAP4R as a gem you must put the following two lines at the

very top of your config/environment.rb

require ‘rubygems’ gem ‘soap4r’

This must be done before Rails starts auto-loading things.

Additionally, you have to put those two lines in every Rails app you have on your machine, even if it doesn’t use SOAP4R! This is, allegedly, because ActiveSupport (in dependency.rb) wrongly loads the SOAP4R included with Ruby instead of your Gem. More details can be found here:

http://dev.ctor.org/soap4r/ticket/433
If you get this error, or similar, in every Rails app

[…]/activesupport-1.4.2/lib/active_support/dependencies.rb:477:in ‘const_missing’: uninitialized constant XSD::NS::KNOWN_TAG (NameError?)

you’ve hit this problem.

Getting Started

If you installed eBay4R from a tarball or git repo, 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’ 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’ 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: #respresp.timestamp”

# Wasn’t that easy?!

Adding an Item ~~~~~~~~~~~~~~

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

require ‘rubygems’ 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 => 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"]))

puts “New Item #” + resp.itemID + “ added.”

Don’t worry too much about EBay.Item and EBay.Category calls for now, they are explained in the “Creating Complex Data Types” section below.

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 <developer.ebay.com/soap/>`_.

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=“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

contrib/

Extras contributed by the community (myself included)

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] NOSPAM- ucla.edu

AIM: garry97531

IRC: up_the_irons in #ram, #git, #caboose on Freenode (and usually many other channels)

Formatting

I’ve dropped RDoc formatting for this README. Headings never looked like headings to me, which was annoying.

This README is formatted in reStructredText [RST]_. It has the best correlation between what a document looks like as plain text vs. its formatted output (HTML, LaTeX, etc…). What I like best is, markup doesn’t look like markup, even though it is.

.. [RST] docutils.sourceforge.net/rst.html

Copyright

Copyright © 2005,2006,2007,2008 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