Tauberer On Creating A Good API

Let’s take the common case where you have a relatively static, large dataset that you want to provide read-only access to. Here are 19 common attributes of good APIs for this situation. Thanks to Alan deLevie, Ben Balter, Eric Mill, Ed Summers, Joe Wicentowski, and Dave Caraway for some of these ideas.

via What makes a good API? Joshua Tauberer’s Blog.

This lengthy article provides an interesting set of points that anyone creating an API for a data set or service should at least consider as they create. I think it’s worth listing the points here, but be sure to go read the article to get all of the details. Then think of these things when you are creating your API.

  • Granular access
  • Deep filtering
  • Typed values
  • Normalize tables, then denormalize
  • Be RESTful , and more
  • Multiple output formats
  • Nice errors
  • Turn intents into URLs
  • Documentation
  • Client libraries
  • Versioning
  • High performance
  • High availability
  • Know your users
  • Know your committed users more
  • Never require registration
  • Interactive documentation
  • Developer community
  • Create virtuous cycles

I think it is also interesting to consider these points when you are developing applications that consumes data or services through an API. If the API you are using is deficient on any of these points consider contacting the API’s developer to see about making the API better.