While at Google, Joshua Block presented in 2006 How to Design a Good API and Why it Matters in the context of one of the most widely used APIs ever created – the Java Core APIs – which may have been used by up to 10 million developers.
He cited a two main reasons why API design is important, including:
- APIs can be among a company’s greatest assets.
- Public APIs are forever – you have one chance to get it right.
Fast-forward nine years later and everything Joshua said holds true, even if the technology and approach for creating APIs is vastly different today. A well-designed API can be a tremendous asset to your company and if adopted by your developer community it can grow your business in ways you might never have anticipated.
Today Twitter’s API handles over 13 billion API calls a day and there are over 750,000 developers around the world contributing applications to the Twitter ecosystem. There are over 9 million applications built on the Facebook Open Graph API. Neither of these companies could have built out the application ecosystems they have today without having great APIs in place.
So how do you design a great API? Is there such a thing? What does it look like?
Keep it simple
Make your API simple and easy to understand. Follow a RESTful approach and model your API after HTTP resources and actions – the same way a browser interacts with the web.
Here is an example of a REST API from a well known subscription billing company.
The API is intuitive and you can tell what it does at a glance.
However, beyond the technical advantages of using REST, modeling your API after real-life things and relationships in your business has a real advantage.
Take the following example.
You can immediately see that this API call returns the address for a specific invoice for a particular account. It’s modeled on real life example. You can imagine a customer on the phone saying “Hi, my account number is 6242525. I have a question. Could you pull up invoice number 345?
Taking this approach means you end up with a common and meaningful language throughout your API that maps to your business and makes it easy for developers to understand.
Another benefit of following RESTful practices is that many API calls can easily be invoked via your browser address bar which makes trying them out relatively simple.
Leverage new standards
Say goodbye to your old friends – XML is out and JSON is in. While many APIs still support XML, many developers are building new APIs to only respond with JSON. Twitter threw its hands up and now only supports JSON after determining that XML usage was significantly low and JSON was more lightweight and developer friendly. Box ditched XML support after learning that it was horrendous at talking about objects and that less than 0.5% of users still wanted to use it.
Protect your loved ones
Use SSL, without any exceptions. It’s easy for hackers to eavesdrop and hijack credentials from users and only supporting HTTPS provides safeguards against this. In addition, when using this approach access tokens can be used instead of requiring users to digitally sign each API request with expensive cryptographic hash functions.
Use OAuth or an open standard for authorization versus creating some custom solution. It will give you more leverage than rolling your own solution that requires every developer needing to figure out how to use it and all its intricacies.
Put your users in control
Giving a user control over how the API operates is a powerful thing. This comes in many ways including the the ability to sort using various rules, searching and filtering. Field filtering is the ability to specify which fields should be returned in the response data. This can be especially useful in cases where there are bandwidth or performance issues, or where a user only cares about a very small subset of the API response data. Another benefit of this is that it limits the need for the API creator to have “different flavors” of the API since it is configurable by the client at runtime.
Show us around
Navigating an API and being able to paginate is especially important when dealing with large sets of data and most SaaS APIs (and many web APIs) fall into this category. Instead of requiring a user to ‘figure out’ where to go next by manually constructing URLs, have your API ‘tell the user’ where to go to get the next page of data. The following is a good example from Facebook’s Open Graph API in which all responses return a ‘paging’ attribute which tells a user where to go to get the previous or next set of data. It’s simple and has the added value that a computer or crawler could use to navigate its way around your API.
Don’t break your users
Every API needs to support versioning in order to provide backwards compatibility and a way for users to bind themselves to a specific version if necessary. The easiest way to do this is to implement a version number into a base URI and also support the latest API version under a versionless base URI. This way API client developers can choose to lock themselves into a specific version of the API or always work with the latest one available.