blog

The Little Manual of API Design

by | Feb 28, 2013 | Developer Blog | 4 comments

Software screen capture
This morning, a reference to a short and well written PDF written by an engineer at Trolltech/Nokia came through my feed reader. It’s only 33 pages long, and every one of those pages has solid guidelines, recommendations, and examples (both good and bad) of considerations you should keep in mind when developing an API of any kind:

This manual gathers together the key insights into API design that were discovered through many years of software development on the Qt application development framework at Trolltech (now part of Nokia). Whendesigning and implementing a library, you should also keep other factors in mind, such as efficiency and ease of implementation, in addition to pure
API considerations. And although the focus is on public APIs, there is no harm in applying the principles described here when writing application code or internal library code.
I don’t think that anyone would disagree with the Apple Pie and Motherhood list of ‘Characteristics of Good APIs’ that are listed:
  1. Easy to learn and memorize
  2. Leads to readable code
  3. Hard to misuse
  4. Easy to extend
  5. Complete

(and reading that list makes me think back on my years of writing C and C++ code using the WIn32 APIs and cry a little), but this document goes past that to outline a well-considered process for designing an API, and guidelines to follow when designing an API, concluding with the very Zen  “The best API is no API”.
Do check it out.
The Little Manual of API Design
(image from http://sofa.projects.semwebcentral.org/doc/design/index.html)

+ more

Accurate Timing

Accurate Timing

In many tasks we need to do something at given intervals of time. The most obvious ways may not give you the best results. Time? Meh. The most basic tasks that don't have what you might call CPU-scale time requirements can be handled with the usual language and...

read more