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