The Author Online Book Forums are Moving

The Author Online Book Forums will soon redirect to Manning's liveBook and liveVideo. All book forum content will migrate to liveBook's discussion forum and all video forum content will migrate to liveVideo. Log in to liveBook or liveVideo with your Manning credentials to join the discussion!

Thank you for your engagement in the AoF over the years! We look forward to offering you a more enhanced forum experience.

CElliott (12) [Avatar] Offline
Will you please put some or all of the ideas in Henning, M. (2007). API Design Matters. ACM Queue, 5(4), 24-36 into The Design of Everyday APIs. I could not finish Irresistible APIs and promised never to look at it again because I could not find any of the classical ideas about API design in it, and, of course, no amount of pounding on my desk, the keyboard or the computer could make the examples work.

API design is important to computer programmers because they deal with it every day in their work, using the C++ Standard Library, the Java Documentation, Mathematica, old LISP manuals, The Collected Algorithms of the ACM, etc., etc., etc. It is also important that APIs be maintainable and maintained. You cannot just throw new routines at a library without any thought of consistency of presentation, organization, encouraging use, and people finding them again. There is no point in proselytizing code reuse if programmers can't find the stuff again and the documentation is not clear, concise, and complete.

I any case, I wish you the best of luck with your book. Speed of completing the work may not be important. What may be most important is that it be a great book that you and the rest of the world treasure for a very long time.
Arnaud Lauret (10) [Avatar] Offline
To the request "Will you please put some or all of the ideas in Henning, M. (2007). API Design Matters. ACM Queue, 5(4), 24-36 into The Design of Everyday APIs", I answer "Yes! Definitely!".

I didn't knew this article and found it on It's really an interesting one for people willing to read my book. The Design of Everyday APIs is about Web APIs and not "library APIs", but this article and my book share the same spirit and these two types of APIs share the same basic design principles.
Here are some quotes from the article that I particularly liked:
APIs should be designed from the perspective of the caller.
APIs should be documented before they are implemented.
Good APIs are ergonomic.
An API must provide sufficient functionality for the caller to achieve its task.
An API should be minimal, without imposing undue inconvenience on the caller.

All these topics are discussed in the Design of Everyday APIs. I describe the consumer's (or user or caller) perspective vs provider's perspective in chapter 2 (Designing an API for its users). Ergonomics is the backbone of the book and is explored in depth in chapter 2, 5 (simple APIs), 6 (predictable APIs) and 7 (Intelligible APIs). Documentation is discussed in chapter 3 (describing an API) and 11 (Growing an API).

Thank you very much for pointing me out this article and for your support!
Arnaud Lauret (10) [Avatar] Offline
And some other quotes (definitely a great article smilie):

It takes time and a healthy dose of "once burned, twice shy" to gather the expertise that is necessary to do better. Unfortunately, the industry trend is to promote precisely its most experienced people away from programming, just when they could put their accumulated expertise to good use.

The idea of the book is to lessen the "once burned, twice shy" thing smilie, so many of my burns could have been easily avoided.

The effects of poor APIs, however, go far beyond inefficient code: poor APIs are harder to understand and more difficult to work with than good ones.

See chapter 1 which is available freely.

Much of software development is about creating abstractions, and APIs are the visible interfaces to these abstractions. Abstractions reduce complexity because they throw away irrelevant detail and retain only the information that is necessary for a particular job

This is the core topic of chapter 2.
antonmry (2) [Avatar] Offline
Awesome article, CElliott, thanks for sharing it