As a developer I am most happy writing code for other developers to write code with. I attribute this in part to the fact that I don’t enjoy writing user interface code as much as writing the code that no-one sees. For me, my favourite user interface is an API or even a web service.

One of my favourite books about APIs is Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries by Brad Abrams and Krzysztof Cwalina. I’ve been reading Brad’s Blog for quite some time and today he posted a link to a really good presentation by Joshua Bloch about designing good APIs. The presentation is video with the full slide deck, and covers a range of topics from the initial specification of an API, through implementation considerations with some specific references to good and bad APIs. I found the parts about specification of an API and avoiding implementation details leaking into the published API and controlling the interface of the API.

Things I took away from watching the presentation:

  • Consult people about the specification - get as much input as possible before committing to a design
  • Keep the interface simple - over complication makes using the API confusing - Usability is important for APIs, stick to naming conventions already in use for your platform
  • Control what you expose - don’t let internal implementation escape through your API, control the exceptions and types you expose
  • Documentation is important - make sure all public parts of the API are documented, the level of reuse of your API will be defined by the how good the documentation is
  • Consider performance of your API - make sure its not going to cause any horrid performance characteristics
  • Subclass only when the type is really a sub class of the parent type (Liskov Substitution Principle)
  • Don’t make the client do work if the module can do it for you - avoid the need for boiler plate code to use your API
  • Report errors as early as possible - compile time is best, runtime is worst
  • Be careful about your parameters - use the most appropriate types, keep the number of parameters under control, make sure overloads are obvious
  • When throwing exceptions give as much information about why the error occurred as possible

The list above is not exhaustative, I highly recommend watching the full presentation - its well worth the 68 minutes it will take.