How to Design a Good API and Why it Matters by Joshua Block, Principal Software Engineer at Google

youtube.com

In my search for stuff to listen to, I Google’d “the best programming talks” and this was one I stumbled on in a comment thread somewhere out there on the internet.

As I’m not a real computer programmer (but as Pinocchio said, maybe someday) I like to find talks that take a broader perspective and explore principles applicative to any discipline, be it programming, design, or maybe just woodworking. This talk had some of that, thought it was also quite technical at times. Anyhow, I wanted to just make some notes on the tidbits I liked (the slides from the talk can be found here).

Implementation Should Not Impact API

Don’t let implementation details “leak” into API

I think this stood out to me most because it’s something I’ve seen happening a lot at my current job: the technical details of a particular service or API has leaked into a user-facing product and become a mental model for both internal employees and external customers. The problem with this, as the speaker points out, is that it inhibits the freedom to change the implementation in the future because people depend on it.

Names Matter

Around minute 31 he talks about how your API is a little language unto itself. You should be consistent and regular where terminology is largely self-explanatory. If you succeed in naming things consistently and simply your code can end up reading like prose, which is generally an indicator of a well-designed API, i.e.

if (car.speed() > 2 * SPEED_LIGHT) {
    speaker.generateAlert('Watch out for cops!');
  }

Using Conventions

Around minute 39 he started talking on how you should borrow conventions from existing languages and platforms. Some of his points included:

  • Obey standard naming conventions
  • Mimic patterns in core APIs and language
  • Don’t transliterate APIs

His point, which I think can be generalized to any profession, is that if you build with concepts people are already familiar with, it can lend simplicity to your product. If somebody knows how to use a native convention in a programming language or ecosystem, they’ll know how to use yours. But don't transliterate he says. If you’re building for C, don’t learn everything about C’s way of doing X and mirror that to your tool. Plus what was correct in C may not be correct for your particular implementation. It’s good to step back and ask “what is this trying to do?”.