Havoc's Blog

Over the holidays I thought I’d play with the Amazon and eBay web services APIs.
What a contrast! I got Amazon working in a couple of hours, and eBay… well, it’s
two days later and I’m starting to feel stupid.

For Amazon, to get information on a product you just register to get
an ID for your application, using your existing Amazon account if you
want, and then you plug that ID into a link
like this and the HTTP GET returns a bunch of XML. So you have
your Amazon username/password, and one application ID string. There’s
also a “shared secret” used for any calls that require authentication,
but most calls don’t require it. Both application ID and shared secret are viewable online
as part of your account.

Amazon has SOAP too, for masochists, but I think I remember reading that only 1% of their API
users bother with it.

That’s the straightforward way to do a web services API. Now let’s
see what eBay has. First, there are three different
username/password logins and it’s never clear which to type
in. Since they’re all on the same site, your browser will try to
autofill the login fields, usually with the wrong one.

Here’s what makes it even more awesome: the three logins at times I
don’t understand seem to interfere with each other by using the same
cookies. So e.g. you can try to log in to ebay.com and it will
redirect you to sandbox.ebay.com, things like that. Basically you need to use
Firefox for one site and IE for the other or something. Which is fun
since I can’t keep straight which login is which in the first place.

After you create your account (one of the three), eBay sends one time
via email three different ID strings; “developer ID,” “application
ID,” and “certification ID.” If you lose this email you are hosed,
they’re only sent one time.

Now you go to the “sandbox” fake-eBay web site and create a fake
user. Only you don’t want to do it on the sandbox itself because you
have to make up all the bogus info (credit card, address, etc.);
there’s a tool to make fake users without entering all that, but it’s
not on the sandbox site, you have to find it separately.

Fake user in hand, you go back to the developer site and manually
cut-and-paste into a form your three ID strings, and then log in as
the fake user, and it gives you another ID string specific to
the user. Only in my case it doesn’t; it says one of my three ID
strings is invalid. Stuck at this point (help?).

If I could get past that, then I could make an API call in the
sandbox environment. But I still wouldn’t be done. Next I’d have to
go through a certification process and get three more ID strings to
use with the production environment, generate another ID string using
a production user account, and I think finally be able to make a
simple API call to get real data from the site.

Let’s review, to make one call you end up with:

• At least 4 separate login/password combinations
• At least 8 tokens or ID strings

This is to get public information that anyone could anonymously screen-scrape.

I haven’t even started to complain about the API itself. Rather than a simple GET, you have
to do a POST with special headers. You are already POST-ing an XML document, so the
information could just be in the XML document; but nooooo. Then the headers include:

	X-EBAY-API-SESSION-CERTIFICATE: devId;appId;certId
        X-EBAY-API-DEV-NAME: devId
        X-EBAY-API-APP-NAME: appId
	X-EBAY-API-CERT-NAME: certId
        X-EBAY-API-CALL-NAME: callName

So yes, you have to put in each of the three IDs twice (someone send
eBay the docs on split() and join()); and you have to put the callName
in there, even though it’s also in the XML document. I imagine this is due to
some internal system that wants to route via HTTP header, or some other
implementation detail, but geez.

eBay does have prebuilt SDK code in various languages to do this for you, but
to me one of the whole ideas of web services is that you don’t need a special library
SDK. I would much rather they’d spent time making it easy to use the service than
coding SDKs in a bunch of languages.

Other frustrations I encountered:

• For the first 6 hours I was trying to use it the API servers were apparently
  just broken; they would hang forever and then close the connection, without returning
  any errors
• There are several different unrelated bits of documentation, some of them discoverable
  only via the forums
• The documentation is in some crazy format where the links are javascript and
  thus opening in a new tab won’t work
• The schema of the XML files seems like a raw database dump, while Amazon has some
  nice “pre-cooked” fields and other useful information.

What makes all this really painful is that in most cases it would
have been better if eBay had just spent less time on it and
kept developer site, API, and docs simpler. Instead of rolling out a
Content Management System for their developer site, they could have
just made their Getting Started page possible to find… seriously, I know
I saw it but now it doesn’t turn up in a search for “getting started” nor
does it appear to be linked from anywhere obvious…

On the plus side, the eBay dev support staff seems pretty responsive in the forums
(where there are lots of questions and confused people related to all of the above…)

(This post was originally found at http://log.ometer.com/2005-11.html#26)