In the last 3 years I have researched hundreds of APIs from SaaS based applications from around the world, analysed in detail around 60 APIs and deep dived into around 20 APIs. I’ve experienced working with great APIs, not so great APIs and everything in between.
Background
To understand what I’ve learnt, let’s take a look at why I have been doing what I’ve been doing. My focus was to use the APIs of cloud apps and integrate between them. This meant that a business owner who has an accounting app, a payroll app and an inventory app to run his or her business could see at a high level, cross pollinated data across these apps to help determine the health of the business very quickly.
A great concept, but the reality is a little different. There is a real melting pot of API capability from the great such as Salesforce and Amazon to the not so great.
The goal of an API
An API is a window into another application’s dataset. Companies create APIs to allow the creation of new applications that leverages its data. So the goal is to be as easy to use as possible and to provide a rich data set to be of some use. Like they say, information changes situation.
What I’ve learnt?
Authorization:
The data owner must have control over who can access the data. I’m strongly hinting at OAuth here. This is a no brainer. Access via a API key or token is synonymous with using a password. What is the difference between “mysecretpassword” and “A3d7!jd*3iulkUkeokqnzYd3”? Oauth allows the data owner to revoke access at any time at his or her discretion. It also allows the owner to provide access to a subset of data and means the owners credentials don’t need to fly around the internet in email chains or in instant messages.
Documentation:
The first thing that anyone does when looking to use an API is to understand what it does. API documentation needs to be clear and accurate. There is nothing more frustrating than reading documentation and then testing the API only to find that a call has been deprecated (not used anymore) or that the content-type needed to be a certain value but wasn’t mentioned.
Examples:
This needs to be provided period. Don’t just talk about. Show me. Real code that users can copy & paste and test. Ie something works. Providing examples in multiple languages such as Node, C#, Ruby, Go, Bash is even better.
Sandbox Account:
If you want users to use your API, make it easy to get a trial of the application and connect to it. I’m happy to say that a lot of SaaS apps do this which is really great to see.
Support:
This is inevitable. Whether you support via Zendesk, community forums, email, IM or a phone call, this is required. It is not often that someone will read the documentation and understand everything perfectly. In other cases, a developer might want to get the information quicker instead of scouring the documentation you so beautifully wrote.
Where am I going with this?
Great APIs don’t just appear overnight. They are built over time with a dedicated team who eat, sleep and breath this stuff or at least they should be!
So whether you are a consumer of APIs or a producer of APIs, here are some points to consider when designing APIs or evaluating and consuming them.