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