When Dion and I joined Palm several years ago during the webOS era, I was very disappointed to learn that we had embraced a second-class public API strategy. While both Palm and third-party apps shared WebKit and a UI library, the Palm-specific hardware stuff was segregated into two APIs: one for trusted Palm developers and another entirely separate set of APIs for the public.
While this wasn’t the root cause of Palm’s failure—that’s another story—it resulted in a comically impoverished API that, for example, didn’t allow developers to vibrate the phone, access the camera directly, or even play audio with any predictable latency (i.e., sounds would play anywhere from 100 ms. to 2000 ms. after you made the API call). This was while developers were shipping amazing, world-changing apps on iOS.
It doesn’t take a genius to understand that in our world of scarce resources and intense competition, such a strategy isn’t likely to result in a robust developer ecosystem. It’s hard enough to keep up with public demand for opening up some of the private API calls; to have an entirely different set of APIs written from the ground up for the public takes the challenge to a whole new level.
When we tried to get the public APIs fixed, engineering managers were sympathetic, but they were constantly making difficult trade-offs with consumer features. They didn’t feel the pain themselves because they had their own private API—and they had plenty of enhancements they needed to make to that one.
More recently, I was reminded of this lesson by examining a very large company’s public APIs for manipulating web-based office documents.
This company is extremely profitable and prides itself on having the best engineers in the world. They point to their high engineering standards and boast about their ability to solve problems that no other company can touch.
I have been using this API on a personal project through a simple wrapper library and have been getting inconsistent results and unanticipated errors. I figured my wrapper library was at fault and that the raw APIs would blow me away with their stability and feature-set.
Well, they did blow me away, in a sense. First, the documentation was atrocious, with one set of docs pointing to another set, which in turn claimed to be deprecated and pointed to a third set, which it turns out covers the APIs for an entirely different set of products.
Bad docs wasn’t a big surprise; this isn’t the first group of engineers to under-document their project.
Fortunately, since this is the web, I can just examine the wire protocol and figure out the gaps in the docs. Except, this company’s web-based apps use an entirely different API than the API exposed to the public. To be clear, both are exposed, but it’s one thing to examine a reference app to fill in holes in docs, and another to reverse-engineer an API from scratch; I have nowhere near enough time to do the latter (and outwit whatever security mechanisms are designed to prevent me from succeeding).
Please, if you find yourself creating consumer products with a public API, do your third-party developers a favor: expose a subset of your internal API; don’t create a new, separate public API.
Ben Galbraith 