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.

I spent some time looking around for a good solution to this problem. I assumed it would be a simple configuration issue but it turns out the format of these messages is hard baked into the ActiveRecord::Errors.full_messages method.

The best solution by a mile that I found was on Adam Hooper’s blog. Adam quite rightly points out that this is a fundamental internationalisation (”i18n”) issue. Although his solution might seem a little more long winded than some, it is the only solution that I found that would work with multiple languages, leveraging Rails’ i18n features.

Here is the full link to the article on Adam’s blog.
http://adamhooper.com/eng/articles/5

1. Update Ubuntu before we start
$ sudo apt-get update
$ sudo apt-get upgrade

2. Check whether MySQL is already installed
$ mysql --version
mysql Ver 14.12 Distrib 5.0.75, for debian-linux-gnu (x86_64) using readline 5.2
MySQL was already installed so OK to proceed.

2. Install Ruby
$ sudo apt-get install ruby irb rdoc
$ ruby -v
ruby 1.8.7 (2008-08-11 patchlevel 72) [x86_64-linux]

4. Install Ruby Gems (the Ruby package management system)
There are two ways to install Ruby Gems on Ubuntu, either through apt-get or by downloading the Gem archive and running the set up script. I tried the apt-get method as that looked quicker:

$ sudo apt-get install rubygems1.8
$ sudo gem update --system

Unfortunately the apt-get package disables the gem update --system and insists that you use apt to update instead. This might be more preferable to the Linux Sysadmin crowd but I prefer to keep everything pure Ruby. It's a few extra commands but nothing too bad.

$ wget http://rubyforge.org/frs/download.php/60718/rubygems-1.3.5.tgz
$ tar xzvf rubygems-1.3.5.tgz
$ cd rubygems-1.3.5/
$ sudo ruby setup.rb
$ gem -v
$ sudo gem update --system

5. Install and test Rails
$ sudo gem install rails
$ cd
$ rails hello
$ cd hello
$ script/server
...
/usr/lib/ruby/gems/1.8/gems/rails-2.3.3/lib/initializer.rb:271:in `require_frameworks': no such file to load -- net/https (RuntimeError)

A quick Google of this error message revealed that I probably should have installed the Ruby OpenSSL library when I originally installed Ruby.
$ sudo apt-get install libopenssl-ruby
$ script/server
This time the Mongrel server started fine.

6. Install Passenger (mod_rails)
The Rails community seem to all be switching from Mongrel to Passanger, the mod_rails Apache plug-in module. I was keen to see how a Passenger deployment compares to Mongrel.
$ sudo gem install passenger
...
Failed to build gem native extension.
Apparently the libraries needed to build a Gem that contains native code isn't included with the main Ruby package, you need to install the Ruby Dev package too (something else I should have installed when I installed Ruby).
$ sudo apt-get install ruby1.8-dev
$ sudo gem install passenger
$ sudo passenger-install-apache2-module

Following the prompts and messages on screen it turned out I didn't have a number of Apache libraries. The passenger installer is very good and gives you the exact commands to run:
* To install Apache 2 development headers:
Please run apt-get install apache2-prefork-dev as root.
* To install Apache Portable Runtime (APR) development headers:
Please run apt-get install libapr1-dev as root.
* To install Apache Portable Runtime Utility (APU) development headers:
Please run apt-get install libaprutil1-dev as root.

I only needed to run the first command as the other two packages must have been pulled in as dependencies.


$ sudo passenger-install-apache2-module
...
The Apache 2 module was successfully installed.