The Little Manual of API Design

Trolltech’s Jasmin Blanchette has written a manual outlining how to best design APIs. Since APIs are a type of user interface (albeit a text-based one aimed at programmers), many of the lessons taught by this document apply to all user interfaces. I think it’s worth reading for UX designers in general, not just API designers.

I particularly like the section on misuse. Blanchette notes that well-designed APIs are hard to misuse.

A well-designed API makes it easier to write correct code than incorrect code, and encourages good programming practices. It does not needlessly force the user to call methods in a strict order or to be aware of implicit side effects or semantic oddities.

This clearly applies to design in general. Your application should be resilient to error. Each of the user’s actions should have a plain and obvious effect, and if possible, the order in which actions are triggered should not influence the result.

I also like what Blanchette says about consistency:

«Consistency» coincides broadly with «conceptual integrity», the principle that a complex system should have a coherent design, reflecting the vision of one architect. Decades ago, Frederick Brooke wrote:

«I contend that conceptual integrity is the most important consideration in system design. It is better to have a system omit certain anomalous features and improvements, but to reflect one set of design ideas, than to have one that contains many good but independent and uncoordinated ideas.»

One only needs to look at an application like iTunes to see what happens if complex systems are designed one feature at a time, without a coherent, overarching vision.

There’s one final point Blanchette makes that I want to highlight. He writes:

Beware of false consistency

Asymmetry of function should be reflected by asymmetry of form.

It’s easy to take «consistency» to mean that everything should be the same. That’s wrong, however. Consistency also means that different things should be different, to prevent people from forming wrong expectations.

Via Michael Tsai.

If you require a short url to link to this article, please use


If you liked this, you'll love my book. It's called Designed for Use: Create Usable Interfaces for Applications and the Web. In it, I cover the whole design process, from user research and sketching to usability tests and A/B testing. But I don't just explain techniques, I also talk about concepts like discoverability, when and how to use animations, what we can learn from video games, and much more.

You can find out more about it (and order it directly, printed or as a DRM-free ebook) on the Pragmatic Programmers website. It's been translated to Chinese and Japanese.