Designing an API – Discoverability

3 Apr 2015

This is part 1 of 3, part 2 is now available, as is part 3, though you’ll probably want to read this first…

Facebook, Stripe, Eventbrite, Shopify, Basecamp, Twitter, APIs are a huge part of our web experience, they connect services, create ecosystems, and allow us to expand the products we use and love.

If you've worked with the APIs in this list though you’ll know some are better than others. So what makes a good API?

Here’s three important factors that differentiate good APIs from poor ones:

The first of the three is Discoverable; which means quite literally “the ability to be discovered”, or in non-dictionary parlance, “I can guess related API endpoints once I know one of the endpoints”. In other words, given the following endpoint:

  GET  /account/1/users

I should be able to guess the next four endpoints:

  DELETE  /account/1/user/1
  GET     /account/1/user/1
  PUT     /account/1/user/1
  POST    /account/1/user

If you’re used to writing Rails this pattern will look very familiar, Rails has encouraged RESTful URLs for a long time, and they’ve also become popular in other communities.

At first glance this RESTful style of API design appears to offer few benefits, however given the following two endpoints, could you have correctly guessed the second, knowing only the first?

  GET  /user_get
  GET  /user_list_events

These two endpoints are from the legacy V1 Eventbrite API.

The ability to guess endpoints can be incredibly helpful when working with an API, it reduces the amount of time spent reading documentation and creates a sense of predictability, of trustworthiness, and ultimately makes me more likely to want to use your API again in the future.