Joshua Bloch on API Design

I was looking for some direction for what people have found works well for API and SPI documentation, when I happened across this great Google Tech Talk on API Design by Joshua Bloch.  Within a couple of minutes I’d started to take notes – which is challenging when you’re trying to eat soup.   It was that good.

To save you (who is likely me as nobody else reads this blog!) from watching the whole 60 minutes again, here were the main things I took away.

The first two were the principles that Joshua wanted to ensure everyone took with them

  • The API should be as small as possible, but no smaller.  “When in doubt leave it out.”
  • Don’t make the client do anything the module could do.  This causes boilerplate code, full of errors.

I like those two principles, as well as the others he highlighted (names matter, strive for symmetry, document religiously, design for performance without warping the API, coexist peacefully with the platform, minimize mutability, design and document for inheritence or prohibit it, keep the Principle of Least Astonishment, fail early, fail at compile time, provide programmatic access to data available in strings, use consistent parameter ordering, avoid long parameter lists, avoid returning a value that requires exceptional processing).  However, what I thought were really interesting were some of the ideas he suggested for the approach to API design.

  • Start with a one-page version of the specification The idea here is that as the specification gets larger and more fully fleshed out, it gets harder to change, and you want to be able to take on feedback from your clients to improve the design as much as possible.  I think it would have a couple of fabulous side effects as well, that make me wonder if you shouldn’t strive for a single-page specification all the time.  First, a single page constrains the size of the API, ensuring that the module does one thing and does it well.  The second benefit might be that keeping a specification on a single page might force the designer to really concentrate on getting the naming right so that the behavior of the API is apparent without so much documentation.
  • Try coding to the spec before implementing it There is nothing like using a system to expose its usability, and for APIs, usage is about code.  As with the single-page specification, this idea has the effect of catching problems while they are easy to fix.  I like the way this principle could tie in nicely with test-driven development, as well.  You know, if you wrote all the tests against a stubbed version of the interface, and they were all failing to start, that would be okay, and you’d have an excellent sense of how to use the interface.
  • For service provider interfaces, write three implementations before publishing For us, service provider interfaces are in fact far more important than application programming interfaces, and so, I wish I’d thought of this myself.  That you need to build something three times before it is reusable is one of those well-known tenets of programming, but I’d never put it together with service provider interfaces before.  Now it seems to make perfect sense.  If you write a single example implementation of the SPI, you will design an SPI that supposes that implementation, two is better, three is really good.  There are diminishing marginal returns after three.

Well, as I say, it was a great talk, well worth watching, and the points I took out of it are well worth remembering.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: