Tag Archives: api

How to Design a Good API and Why it Matters

An interesting presentation from Joshua Bloch – How to Design a Good API and Why it Matters. It’s exactly what it says it is, with plenty of examples from Java.

Some of the interesting points he makes:

  • an good API can be an asset, but a bad one a liability – you have only one chance to get a public API right
  • Will Tracz’s “rule of threes” – write 3 plugins/interface implementations before release to make sure you’ve got the interface right
  • bad design decisions can limit performance
    • (an example I see sometimes is “Thing getThing(K id)” provided, when I want to get multiple Things – it would be good to have e.g. “Thing[] getThings(K[] ids)”
  • Methods should be failure-atomic – succeed or fail, not leave things in some half cooked state
  • Provide programmatic access to all data available in string form
    • otherwise people will parse it – example given of stack trace in Throwable
  • Use consistent parameter ordering across methods
  • Easy to make mistakes with long lists of identically typed parameters
  • If too many parameters, make a helper class to pass them in
  • Return zero-length lists, not null
  • Overuse of checked exceptions causes boilerplate
Finally, another rule I’ve heard before is this:

simple things should be easy, complex things should be possible

Web APIs

Interesting article over at The Register about building on someone else’s API or platform – Total bankers: Twitter and LinkedIn’s cynical API play.

It’s worth remembering that to an extent, companies expose APIs for their own benefit. If you build on them, the carpet might be pulled from underneath you when what you’re doing  doesn’t fit the owner’s needs and goals.