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

designed for use cover

But wait, there's more!

Want to read more like this? Buy my book's second edition! Designed for Use: Create Usable Interfaces for Applications and the Web is now available DRM-free directly from The Pragmatic Programmers. Or you can get it on Amazon, where it's also available in Chinese and Japanese.