What makes a good api?

What makes a good API?

  • Good Documentation
  • Working Examples and Tutorials
  • Clear Status
  • Good Support

Lets walk through these in detail

Good Documentation

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.


Mapbox, does a great job of this, take a look at their api: https://www.mapbox.com/mapbox.js/api/v2.1.9/

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.

JS Fiddle 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.

Clear status

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.

Vimeo Status Screenshot

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

AWS Status

Good Support

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/

An API interface that provides services like rate limiting, authentication, logging, check out Kong or 3Scale

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.


About davew

I am a product manager at a tech company. I love building things.
This entry was posted in Uncategorized and tagged . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s