What makes a good API great?
A great API is thoughfully designed. Spend time in understanding users, simplifying the offering, and getting the basics right.
At Trackmemo, we integrate with multiple applications to build a single feed of updates for users. In the course of integrating with 8 APIs and evaluating almost 50 others, we have loved some and hated a few, and spent countless hours debating the true path of API design. Here are a few things that we now agree on.
Design with Intent
APIs are not meant to enable replicas of your application. They enable use-cases that your core application does not address but your data can help realize.
Defaulting to “let’s make everything accessible” makes your API needlessly complex and defeats this core purpose. Good APIs are built with a set of clear application stories, much like good products have excellent user stories.
Keep it Simple
Imagine an application where something is called an ‘Apple’ in one place and ‘Orange’ in another. Users would scream murder. The same holds for APIs. The best ones are simple and consistent — built on top of a small set of objects with well defined relationships and operations.
Dropbox’s Core API exemplifies simplicity. It is built around a single object type — Files — and, three operations — read metadata, read content, and upload content. When a developer sees this API, she can easily understand the different things that can be easily accomplished. And this intuitive understanding will ultimately drive her to build with your API.
Have a Quick Start guide
API documentation is the equivalent of user on-boarding in your application. The best ones enable the developer to start using the API productively in minutes. But too often, API documentation is restricted to a reference guide. And in a world of short attention spans, only a few finally get through.
Good ones — like Github — start users with a short Quick Start guide. In minutes one can get the API working and broadly understand the different entities and their relationships, and feel much more confident about building something more complex.
Implement OAuth2
Imagine a world where each application had its own way of logging you in — username/password in one, secret token in another, and so on. Would you experiment with new applications in this world?
And yet, almost every API does this. We spent at least an hour or more on average per API to get authentication right. Some have tokens, others implement their own versions of OAuth1 and OAuth2 specification. Yes, authentication is important but from an API user’s perspective it is a hurdle, not a goal.
With the OAuth2 specification ready, the more mature APIs have already moved to this standard. Why won’t you?
Allow multiple levels of access
The first question when users ask, when authorizing 3rd party applications is “what can this application do with my data?”
The answer, often, is everything. But applications rarely need access to everything. And users are uncomfortable with blanket access rights.
Instead take the Google Drive API. Thoughtfully designed access scopes make it easy for the developers to communicate what they intend to do with the data. Further since the scopes are framed from the viewpoint of the end user rather than the API developer, it makes it easier for the user to trust new applications.
Provide clear feedback on fails (and successes)
API calls will fail. They could be because the developer is doing something wrong. Or because, they have hit the specified rate limits. Or maybe just because something bad happened. Whatever, be the case let the developers know — preferably via HTTP error codes.
Immediate and clear feedback frees the developer from constantly worrying about data consistency. And since HTTP codes have narrow semantic meanings it becomes easier to fix errors and communicate them with the end-users. On your end, it makes future investments easier since you can understand where things need to change just by looking at your access logs.
Provide change detection mechanisms
APIs talk over the internet. And if stuff hasn't changed every call to check is both a load on your servers and additional bandwidth for your users. Implementing a change detection mechanism (like ETags) entirely eliminates this unnecessary chatter.
Google Drive and Dropbox have well designed change-detection APIs. Though not necessary for early versions, this is an absolute must if you want your API offering to scale.
The above might seem basic hygiene, but our experience shows us that most APIs fall short on several of these dimensions. Grab these low hanging fruits early, and you make your user’s life significantly simpler.
