One of the things we do pretty regularly at MichiganLabs is help our clients evaluate the server-side of the mobile project (and regularly help them implement it as well). We often find that the server-side portion of the project can be at least as big as the app development effort.

Google Tech Talks posted a video of Joshua Bloch, one of the designers of Java, giving a talk on how to design good APIs. This is particularly relevant for us we work to define the Server-App interaction, but Bloch also makes a great point that every software engineer is an API designer. When we try to write modular software, our API is basically the way modules interact with each other. Working on large projects with multiple developers highlights this even further. Giving a coworker a header file or interface for the module you’re writing goes a long way in increasing productivity and allowing for parallel development. Even more importantly is not making changes to that interface every five minutes, requiring the coworker to change their code.

Below are some of the notes I took while watching the talk. Most of them are simply the headings from Bloch’s slides. I take no credit for the content, all of it goes to him. At the end of his talk, Bloch makes a reference to API Design by Bumper Sticker. Apparently he had given this talk before and had made a Cheat Sheet with the highlights. Much of it duplicates my notes.

API’s should be:

  • Just powerful enough, not too powerful
  • Appropriate to the audience

Initial Development

  • Use use-cases for determining what is needed
  • Could be more interesting to build a generic version
  • Bounce off as many stakeholders as possible
  • Pretend API exists and code against it – Use this for future testing

Actionable Advice

  • Functionality – Do one thing and do it well, easy to explain
  • Small as possible but no smaller – When in doubt, leave it out, easier to add later
  • Implementation detail should not leak into API
  • Make everything as private as possible, public classes should have no public fields except for constants
  • Names Matter – API is basically a language
  • Document Religiously
  • Don’t make the client do anything the module could do
  • User shouldn’t be surprised by API behavior
  • Provide programmatic access to all data that you have available in string form
  • Overload with care
  • Consistent parameter ordering across methods
  • Strong typing
  • Three or fewer parameters per function
  • Make return values consistent within function