What makes a good API?
- Good Documentation
- Working Examples and Tutorials
- Clear Status
- Good Support
Lets walk through these in detail
If you want people to use your API, it has to be intuitive. The parameters that it takes need to be clear, it needs to follow REST standards (this link itself is a valuable read). Return types and values should also be well defined.
Working Examples and Tutorials
How does your service / API work? Without clear, working examples and tutorials, developers will look past your API, and pick another service that has these things.
With the addition of gists and tools like https://jsfiddle.net/, there is no reason not to have “working” samples available online for your clients to test out and make interactive. See http://jsfiddle.net/rniemeyer/LkqTU/ as an example.
Working examples provide best practices and reference implementations. You can’t assume that the developer can read each other’s mind, so there is no substitue for working code, and a sandbox to test in.
- Firebase allows you to easily switch between the code and a running example:
- Joomla offers a “90 minute test drive”
In the age of instant feedback, when something goes wrong (and it always will, usually right before that super-important demo with a new client), the first question is if the service is working. A clear status page helps people know if things are working as expected, or if there is an issue. For example, see http://www.vimeostatus.com/. There is no excuse for not having clear status pages – see https://www.statuspage.io/ for examples. You need to be able to proactively know whats going on, and provide information to your clients. Nothing erodes confidence faster than silence during an operational outage.
Companies like Pingdom are an easy way to make sure your service is “up” and returning some validation.
For app and server level visibility, New Relic is leading the market, but there are other contenders close behind. There are no longer excuses for applications to “go down” or not know where the hotspots are.
Amazon AWS also has a great status page
The barriers to getting real-time direct feedback has fallen dramatically. Using tools like User Voice allows you to this feedback (or some other similar company). Now there is no excuses to hear from your users, and be able to respond.
Devs post questions on stack exchange, quora, and your own forums. Be sure to actively monitor these forums, and respond quickly and accurately. Also empower your customers to respond. This helps build a community of people who are looking out for each other and you.
Some other links / tools
Need a way to “test” an idea – build a landing page, get adwords, see traffic. Check out http://quickmvp.com/
Need to build a data driven service? Check out https://airtable.com/
Want to put something together without coding. Check out http://mobilexlabs.com/
3Scale has written some good posts about managed apis. For example: http://www.3scale.net/2013/10/great-apis-need-api-mngmt-part-iii/
For mocking an API response, check out https://www.mockable.io/
For bootstrapping a project, Deployd is very cool, but its only on version 0.8, and had been dormant for a while.