Saturday, January 13, 2007

eBay API experiences

Lately I have been trying to learn how to use the eBay API to list items and learning exponential representation for complex numbers in Algebra. Using the eBay API is the harder one out of those. Just a minute ago I finally succeeded at listing my very first item by using the XML API, it was a bit more complex than I thought! My mental model for how the API would work was that I would pass my eBay user id and password, along with the item details wrapped in some XML.

Nope, there are several different kinds of keys involved. All in all I currently have NINE different pieces of authentication! I have a DevID, an AppID and a CertID. Then there is the eBayAuthToken and the REST API key (which I admittedly only used once for testing, it is not needed for the XML API). But wait, that's only five? Yes, but you see eBay has two servers -- production and sandbox. The sandbox is for testing, which is useful since listing things on the production server costs money, so you definitely don't want to end up listing ten thousand items by accident. The sandbox and production servers have completely different authentication keys, except the DevID appears to be the same (making it nine different keys total).

The eBay developer site doesn't make this sandbox and production server difference clear. When talking about authentication keys, they casually mention that oh yeah, there is the sandbox server too. But what they don't say (on the intro pages at least) is that you need completely different keys for those. So imagine my frustration at attempting to access the sandbox with my shiny new production keys. With all those different keys I was getting really hopeless and uninformed, mostly reading reddit instead of focusing on the problem.

Somehow after a lot of digging I managed to figure it out. A DevID identifies a developer. A developer may have multiple applications, with each application identified with its own AppID. CertID is a magical entity the purpose of which I don't understand, but things seem to work when I bundle the same CertID that came with the AppID. The eBayAuthToken must be generated on their web page, and generating that requires providing correct DevID, an AppID and a CertID for the server which you are trying to use (sandbox or production). In other words you cannot get an eBayAuthToken for the sandbox server by using the production DevID, an AppID and a CertID + vice versa. The REST key is needed only for... you knew it, making REST calls.

After I finally had my keys I started to read the API reference. I tried to pretend calmness, but actually I was a bit shocked of seeing all the possible method calls and the arguments they take. Huge list. Maybe I'm not enough in the XML camp, but in my mind things work like this: you get a template string of a working XML call, then you change the things which are different from what you want and send that string at the server, which then does something cool. It's pretty difficult to try to come up with something that works by just looking at an API reference if there are 20 different arguments that could go wrong! Luckily, the developer center has very nice examples of using the API, so I was able to get things working by copying and pasting their examples.

Another thing which seemed like a showstopper at first was that they require usage of SSL to access their server. That is an excellent thing of course for security, but complicates things a bit when you are just trying to get a minimal example to work. I was planning on using PHP, but felt a bit intimidated at the thought of figuring out how to get SSL working on it. Just to get acquainted with the API, I decided to stick with Perl as they had some nice Perl examples in the developer center, complete with instructions on how to install SSL support for Perl.

So I had my keys, I had an XML request constructed from the example and I had ActivePerl installed on my box, with LWP and SSL support, aaand... it worked!

Update: After 30 mins of reading some example code I managed to figure out how to make the same request using PHP, HTTPS with cURL! One thing I was worried about was how image uploading would work, but turns out that you can just specify an image URL and eBay's server will go and fetch it -- no need to figure out how to actually upload the data, what a time saver! Just a bit more effort and I'll have this code integrated with my web store.