At the API Academy, we make a habit of studying APIs and discussing them to get better at our craft. We usually do this in private and behind closed doors, but last month ProgrammableWeb gave me an opportunity to write up a public review of the Box API, and I’m happy to have the opportunity to write another. This time, we will be delving into eBay’s set of APIs.
If the web API industry was like the automotive industry, then eBay would be our Ford Motor Company – a historic organization that has enjoyed tremendous success and paved the way for others in the field. Indeed, eBay helped to define the open API scene and has played a leading role in influencing the technology and business of APIs since the company created their developer program in 2000.
The eBay Developer Portal – circa 2001
This success and longevity makes the eBay API a particularly interesting one to study, giving us a rare opportunity to inspect a successful open API that has been around for more than 10 years. Our tour will examine the interface of the API as well as the rest of the developer experience, including aspects of registration, documentation, terms of service and community support.
Input Fields Required: 12
Approximate time to complete registration: 5 minutes
There are 12 input fields that need to be completed in order to apply for an eBay developer ID, including a company name, phone number and captcha to prove that you are a human. Granted, the process isn’t quite as painful as filing your taxes, but it’s certainly heavier than modern portals that have taken a ‘frictionless’ approach to registration.
Registering for an eBay Developer ID
Once you get past that, the process is straightforward – you receive a confirmation email after registering and upon activation generate a set of API keys for your application to use. You don’t need to wait for a human to evaluate your application and you can start making eBay API calls right away with your new credentials.
Architectural Style: Tunneling
Message Formats Supported: SOAP, XML, JSON, Name-Value
Before we examine the interface, it is important to understand that the eBay API is big. Very, very big.
A Sampling of eBay’s API Collection
There are actually 19 individual APIs available within the eBay developer platform, and that number doesn’t include the PayPal or Magento interfaces that exist under the bigger eBay brand umbrella. While a few of these APIs are deprecated, most of them are actively supported, making this the largest public API that I’ve personally encountered.
It’s possible that many of these interfaces are actually calling the same internal services behind the scenes. This provides us with a great illustration of API product management and the decisions that need to be made as an audience grows, regardless of the actual code or data model that is being exposed.
The eBay API products appear to be delineated based on a target audience (e.g. buyers versus sellers) and the type of messaging pattern employed (e.g. request/reply versus pub/sub). While segmenting an API like this can make it easier for developers to focus on the functionality that they will use, it has the downside of increasing complexity and forcing the developer to use multiple APIs when requirements deem it necessary.
Web APIs can be categorized according to their architectural style (i.e. the collection of features and traits that allow us to classify interfaces into groups). The three most popular API styles at the moment are Tunneling, Object and Hypermedia (see this video for a better understanding of these classifications). All of the eBay APIs exhibit the Tunneling style, which is the one most commonly associated with the SOAP messaging protocol.
However, it’s not all SOAP based interfaces at eBay. There is widespread support for the plain XML format, and the search product called the Finding API exposes a URI based interface that is invoked via an HTTP GET operation. But, unlike more familiar Object (or CRUD) style APIs that allow developers to locate resources through URI construction, this URI is a fixed service endpoint upon which query parameters such as the operation to be invoked may be passed. Effectively, the GET based URI interface is the same as the SOAP one except the transport mechanism is different.
There is nothing inherently wrong with implementing a tunneling style API. Good interfaces should be designed to facilitate real usage, and there are many developers for whom this style is both familiar and preferred. However, object style APIs tend to be preferred by mobile and web development communities and eBay may not be hitting the right chord if they want to attract these developers.
While the read-only Finding API might be considered a bit quirky, the Trading API can be downright frustrating to use. Puzzlingly, many standard SOAP and HTTP conventions are not observed including the proper use of HTTP status codes. Developers who have honed their skills integrating with non-eBay APIs will find the experience of learning the Trading API a confusing and difficult journey. Ultimately, developers need to learn the eBay way of API connectivity in order to use the Trading API interface.
Although the eBay group of APIs is rooted in the XML and SOAP based Tunneling style, eBay’s ql.io gateway is an anomaly. Built using node.js, this brainchild of Subbu Allamaraju was released to the open source community in 2011 and delivers an SQL-like JSON/HTTP interface for any HTTP based API. In addition to providing a compelling interface for eBay and other services, ql.io can help reduce the time it takes to make many sequential calls by orchestrating these invocations in parallel.
This is all promising stuff, but unfortunately you can’t use ql.io unless you download the source and deploy it to a node.js server – either locally or in the cloud. Essentially, ql.io becomes a component within the developer’s own application solution, requiring a non-trivial investment of time and money for a production instance. It would have been great to see ql.io integrated into the interfaces at eBay, but I couldn’t find any evidence of a production ready hosted instance.
Level of Depth: Deep
There is a lot of documentation available for the eBay set of APIs and each product has a documentation portal of its own. The docs do a great job of describing all of the intricacies of each API and its context within the eBay eco-system, and there are a healthy number of examples. The challenge comes in navigating through all of that information to find the specific item you need.
I was impressed by the number of tutorials and use cases available on the site. These are great starting points for anyone new to the API and are a good example of how clear navigation and targeted documentation can make a complex interface feel simpler. In addition to the tutorials, there are a small set of code samples, SDKs, an API test tool and a usage reporting tool that tracks metrics for the Trading API.
You won’t confuse the eBay API documentation with the slick, bootstrap-like dynamic navigation sites that modern API vendors are providing. In fact, some of the eBay documentation portals will fill you with nostalgia as you view pages that look to have travelled forward in time from the late 90s.
But putting style aside, the writing is straightforward and the important documents like quick start guides, tutorials and references are easy to find.
If you are building a SOAP or XML based client, your needs will be well served by the documentation. There are easy to find WSDLs and XML schema files for every service, and the reference documentation is structured well. At times the flow of documentation can be frustrating and the lack of consistency in style is off-putting, but if you work hard enough, the information you need is there for you to find.
Surprisingly, almost all of the guides, references and collateral are targeted towards web and server based development rather than mobile developers. I could find very little information pertaining to iOS or Android let alone less popular mobile platforms. Given that mobile is such a huge driver of API growth, the lack of mobile-centric documentation is a problem.
Terms of Service
The conditions for signing up as an eBay developer are fairly clear and laid out in the API License Agreement. I’m not a lawyer, but my reading of the agreement didn’t present any red flags as most of the terms seemed fairly reasonable for an API provider protecting its own interests.
The rate limit for API requests varies depending on the product you choose to use, but the majority of the eBay APIs will limit you to a rate of 5,000 requests per day. Higher volume applications can request a larger limit provided they pass an eBay compatibility certification program, at which point they may request up to 1.5 million requests on the most popular APIs.
Community and Support
One of the really nice things about using the eBay API is having access to their sandbox environment. The sandbox is a simulated eBay site that allows you to test your client application against realistic data without impacting the state of the production version. Testing bid submission and auction management functions would be extremely difficult without this simulation engine, so it is a wonderful feature to have access to.
In general, the developer ecosystem for eBay is good. It isn’t difficult to find code examples on the web, and Stack Overflow has a healthy and active eBay API section. Within eBay’s own x.commerce developer site, a community forum is available and used quite heavily. There are also plenty of examples and sample applications to learn from both in their portal and on the web.
Although there were exceptions, the eBay developer community is primarily peer-to-peer based.
This might be a case of eBay becoming a victim of its own success and being unable to scale their support team to meet demand. The more skeptical might point out that eBay actually charges developers for API support and may not be motivated to provide assistance for free. Either way, the absence of eBay within their online community was noticeable.
Protocols Supported: SSL, custom authorization flow
The eBay interfaces are protected by a set of keys that are generated by developers after they register. This secret key style of access control has become standard practice in the API world, and works well provided that client applications can maintain the privacy of their credentials.
For more sensitive interactions – such as the APIs that allow applications to act on behalf of eBay users – a delegated authorization protocol is used. This scheme predates the OAuth 1 and OAuth 2 specifications, but the basic flow should be familiar to developers who understand OAuth.
Pricing and Cost
Pricing Mechanism: N/A (free for public use)
In the early 2000s, developers needed to pay a membership fee for the privilege of joining the eBay developer program. But 2005 marked a major milestone in web API history as eBay moved to a free model, opening up their API for all to use and acknowledging that the industry was entering the era of developer kings.
While usage of their API is open and free, eBay does charge a premium for technical support. It’s not unheard of for an organization to charge support costs for free products, but it is rare to see it in the web API space. More worryingly, developers must go through this same paid support route when reporting bugs and only receive refunds if eBay concurs that there is a fault in the API.
Paid Support Pricing
While I suspect these charges are in place simply to recoup operating costs rather than for any devious profit motivation, they send a negative message to the developer community. Great developer-publisher relationships should feel like partnerships in which both parties benefit from their association. This sends the opposite message.
Taking a step back, it’s clear that the eBay API is a great success story. There are a massive number of applications using the eBay API and the developer ecosystem continues to thrive. It is clear that eBay’s users have benefitted greatly from the company’s API strategy, given the quantity and quality of third party tools available and the diverse set of platforms through which they can access the site.
eBay’s API products have grown and changed over the years, but for my tastes some of them are starting to feel dated and don’t compare well against the cleaner, simpler interfaces that developers are exposed to now. I don’t believe I’m alone in this view, as it isn’t terribly difficult to find outbursts of frustration with the Trading API from within the developer community.
New API publishers can learn from the example of eBay and take away the lesson that API design is a constant effort, not a one-time exercise. The mark of a great API isn’t simply one that exists for a long time; instead it is one that evolves to meet the changing interaction demands of its audience.