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.
2 replies on “Usable APIs follow-up”
[…] the John Sonmez blogging course. I got back into public speaking, with my talk about APIs, and the follow-up usable APIs guided conversation at CodeCraftConf, although I missed out on the return of DDD […]
[…] is in a predictable place. Because then you can concentrate on the dish, instead of the kitchen. Good preparation helps every task fall into the pit of success, and makes it easier to recover if something goes […]