Using the eBay SOAP API from Ruby-on-Rails

02 October 2009 by martin

This article applies to:
Rails 2.3.4, Ruby 1.8.6, soap4r gem 1.5.8, ebay4r 1.1

I have been taking a look at ways to integrate a Rails application with eBay. They support a number of different programming interfaces and, if you are using Javascript, PHP, Java or .Net, have some good examples to follow. I managed to get a Javascript interface working quite easily from inside a Rails _form view, but it just does not feel like the most elegant solution to me.

Since eBay provide a well documented SOAP API I thought it would be a good opportunity to investigate Ruby's support for SOAP. SOAP support is a standard feature of Ruby and is provided by a library called soap4r. I tried implementing my own call to eBay's GetItem interface, but I encountered a few problems and soap4r's documentation didn't help much either. Then I discovered a library called ebay4r which is built on top of soap4r. The rest of this article describes how I successfully integrated my Rails application with eBay using ebay4r.

Step 1) Load the gems into your Rails application
ebay4r needs a later version of the soap4r API than ships with Ruby. It's easy to install the gem but there are some warnings on the ebay4r and soap4r web sites about how to avoid API version conflicts caused by gem. Adding both via config.gem seems to avoid this problem completely so the workarounds suggested should not be needed. Edit your environment.rb and add the two new config.gem lines shown below :
config.gem "soap4r", :lib => false
config.gem "ebay", :lib=> false

Next, use rake to ensure these gems are installed:
rake gems:install


Step 2) Obtain eBay Authentication Keys
The eBay SOAP api requires that you authenticate with a set of four keys; AppId, DevId, CertId and AuthToken. You get these authentication keys by signing on to the eBay Developers Program. You should be able to view the first three keys from your eBay Developer Account page. The AuthToken is a little bit special. Whilst the other keys are used to authenticate your use of the API, the AuthToken is used to actually determine which user your API calls will run as. Without an AuthToken you can only retrieve public information. I'm not even sure if ebay4r supports making API calls without an AuthToken. To get your AuthToken, click on the "get a user token" link on your profile page and follow the instructions.

Step 3) Set up eBay configuration parameters
ebay4r suggests saving the four authentication keys in a Ruby file called 'myCredentials.rb' and then loading the file to create some global variables. Whilst it works, it's not very Rails. I created a custom initialiser and a yaml config file to hold my values.
#config/initializers/ebay_config.rb
require 'yaml'
EBAY_CONFIG = YAML.load_file("#{RAILS_ROOT}/config/ebay.yml")[RAILS_ENV]

# config/ebay.yml
common: &common
DevId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AppId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
CertId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
AuthToken: xxxxxxxxxxxx ...more... xxxxxxxxxxx

production:
<< : *common

Step 4) Create an application model to represent the eBay Interface
Whilst I could just invoke the ebay4r methods directly from my business logic, I prefer to insulate the rest of my code from an external API. I created an EbayTrader class in my application's models directory:
# app/models/ebay_trader.rb
require 'eBayAPI'

end

Two things to notice:

1. the test method. Throughout the eBay API documentation you will see the GeteBayOfficialTime call being used to test the interface is configured correctly. My test method does exactly the same and makes it easy to test in the script/console.
2. the EBAY_CONFIG built in step 3 is used to provide the authentication keys during initialisation.

Step 5) Test Your eBay API Configuration
Before we go any further it's worthwhile testing to make sure you can actually connect to eBay. Use script/console to run our test method.
$ script/console
Loading Development Environment (Rails 2.3.4)
>> et=EbayTrader.new
...
>> et.test
...

You should see irb output to indicate that the code connected to eBay and returned the eBay Official Time. If not check the errors and try again.

Step 6) Implement Specific Calls to the API
Now we are ready to put our set up to work. The ebay4r library makes calling the eBay APIs very simple. The full list of API calls available can be found on the eBay Developer Program Documentation pages.

eBay are very careful to version their API so that you will be less affected by any changes they make. The underlying SOAP API requires you to specify which version of the API you are using when you make an API call. Version 1.1 of ebay4r was built for eBay API v583, so just make sure that the API call and the parameters you want to use are supported by v583 of the eBay API. Rebuilding ebay4r for the latest eBay API should be straightforward (thanks to soap4r) but is beyond the scope of this article.

I want to use the API to get detailed information about an auction item. The underlying eBay API for this is GetItem, which is part of the Trading API set. If you take a look at the API documentation you can see the in and out parameters for the API call. For GetItem the main in parameter is ItemID, most of the others are optional. ebay4r allows parameters to be passed to an API call as a Ruby symbol. The out parameters are converted you object methods making the results very easy to navigate. So in our model we can use:
# app/models/ebay_trader.rb
...
def get_item(item_id)
result = @eBay.GetItem(:ItemID => item_id)
result.item
end
...


Summary
That's the basic eBay integration done. Accessing the EbayTrader model from a controller or some other piece of business logic should be straight forward. I will add a step 7 to this article in the not too distant future to demonstrate this and to explain more about how to access the results of an Ebay API call. In the mean time just take a look at the examples provided by ebay4r.