It’s common these days for web applications to provide some sort of RESTful API for third party integration, but too many of them are built after the fact, as a lacklustre afterthought — with holes and limitations that makes them useless for all but the most trivial applications. Here’s some common pitfalls I’ve seen (and been partially responsible for!) arising from this style of development:
- Only a narrow set of features supported: The application may have a hundred different tasks a user can do in the GUI, but only a handful are supported through the API.
- Impractical for real-world use: APIs that fail to consider things like minimizing the number of requests through and batching and bulk APIs. Just think, how you would implement GMail’s “mark all as read” button if you could only update one conversation at a time?
- API features lag UI features: For example a new field might be added to the UI, but there is no way to access it in the API until someone requests it.
- Weird/buggy APIs: Bad APIs don’t get as much developer attention if no one’s using them, making them a natural place for bugs and design quirks to harbour.
Instead of restricting developers to a limited, locked-down set of operations, the goal is to empower developers to be as creative and productive as possible with your API.
A better way to design an API
Don’t try to build the sort of API you think people will want. Flip the problem on its head and eat your own dog food: make a rule that, from now on, all new UI features can only be based on the public API. Abandon your traditional, internal back-end interfaces and start using the public API as an interface for all your front-end applications.
“All Google tools use the API. There is no backdoor. The web UI is built on Google App Engine, for example.”
This quote from High Scalability beautifully summarizes the design of their API. There is no backdoor, no privileged internal interface — Google developers have to use the exact same API as you at home.
Twitter is another great example of an application that dogfoods its own API – click view source on twitter.com and you’ll see, apart from tracking and advertising, it’s mostly AJAX calls to their public developer API – the very same API all the thousands of third party apps use.
