Usable APIs follow-up

Following the Usable APIs guided conversation at CodeCraftConf, I wanted to capture some of the thoughts that came out.

Starting an API (as a user or a developer)

  • Does the API documentation include examples of usage (i.e. have they thought about the client)
  • How mature is the API?
  • How well maintained is it?
  • How long does it take to get to the first success (e.g. 200 OK – assuming success doesn’t mean error).
  • What’s the versioning policy?
  • What’s the contract?
  • What’s the shape of the data?

Changing and retiring APIs

  • Never, ever, ever, change the endpoint.
  • Give as much notice as possible of changes (and never negative notice).
  • Provide migration guides to clients, or automation scripts, such as the Python 2to3 migration scripts and guide.
  • Be proactive – there was an example given of a web API (I can’t remember which one, sorry) that changed their endpoint, and created a bot that searched Github for usages of the old URL, and submitted pull requests for the new usage.
  • Deprecate, then kill, once usage falls below a threshold.

Foolproof APIs

Isolation and proxies

  • Log everything to detect unreliability.
  • Make sure proxies are kept up to date with the underlying API, and fail gracefully when the API changes.
  • Expect failure.
  • Data is key – don’t give up more than you have to.
  • Make sure, as a server writer you understand the client, and the network.
Advertisements

One thought on “Usable APIs follow-up

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s