"Does API Value and Reliability Trump Docs and Code Samples?"
05 Aug 2011I've written about the essential building blocks necessary for a successful API, and there are other great posts like, What Developers Say About API Documentation from Peter Gruenbaum of SDK Bridge.
Everyone seems pretty unanimous that a RESTful API, with simple and complete documentation, qualitiy code samples in the popular languages, and real API support from the owner and the community are the ingredients for a successful API.
Iparticipatedin a chat about APIs on Twitter, where amix of API influencers, owners, advocates, evangelists and developers hung out for about an hour, answering questions posed by @retailigence. Overall there were about seven questions asked, but the second one was simple, and thought provoking:
What is the most important characteristic of an API?
The common building blocks were rattled off (by myself included): REST, quality documentation, code samples, while other said more innovative things like API explorer or Masherys I/O Docs. Then @infochimps said reliability & usefulness.
This started some side conversations and got me thinking. Does the overall value an API deliver and its reliability trump its RESTfulness, documentation and available code samples?
I would say definitely, yes! It is true that a RESTful API, with simple and clear documentation, and code samples are a must have. But if your API doesn't offer clear value and reliably deliver on this value, no amount of documentation or code samples is going to work.
These are all pretty basic concepts at first glance, but it is a reminder where to focus your resources when it comes to your API.