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

• Provide helpful errors, and treat unhelpful errors as a bug.
• Guide users into the pit of success.
• Follow existing conventions and standards.
• Be consistent.
• Document all the options and overloads.
• Postel’s Law : “Be liberal in what you accept, and conservative in what you send”.
  • But it’s very, very easy to get it wrong. Just look at IE6 and the broken web.

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.

Advertisement