The other challenge we faced when working on the NetBeans project was scalability of
teamwork. In those early days, back in 1997, I wrote the APIs on my own. The other NetBeans
engineers “just” wrote the code; that is, they provided user interfaces and implementations for
various parts of the NetBeans IDE, while continually making use of the APIs that I provided.
Unsurprisingly, this created a bottleneck. I came to realize that the number of people working
on various NetBeans IDE features had grown to a capacity where one “architect” was unable to
handle the demand for APIs. Over time, change was urgently needed. We needed a majority of
the NetBeans development team to be able to design their own APIs. At the same time, we also
wanted to maintain a certain level of consistency between the APIs created by different peo-
ple. This turned into the biggest problem, not because developers didn’t want to be consistent,
but because I wasn’t able to explain to them what I meant by consistency. Maybe you know
the feeling of knowing how to do something, without knowing how to explain it coherently.
That was my situation: I thought I knew how to design APIs, but it took many months before I
managed to formulate the most important constraints that I wanted others to follow.
A LATE NIGHT API TALK
I’ve been interested in API design and API publishing for a long time. I’ve given various presentations inside
Sun Microsystems and for NetBeans partners on this topic. However, my first public talk that related to this
topic took place during JavaOne 2005 in San Francisco. My friend Tim Boudreau and I had submitted a pro-
posal entitled “How to Write an API That Will Stand the Test of Time.” It was scheduled to start at 10.30 p.m.,
probably because the abstract didn’t contain buzzwords such as “Ajax” and “Web 2.0.”That time of night is
not ideal for a presentation, as we had to compete with parties, free beer, and other late-night distractions.
We were pessimistic and expected one or two friends to show up to console us. Our mood got even worse
when we arrived at the venue and saw that right next door a JDBC driver presentation was going to be held.
The corridor was filled with people. Our assumption was that everyone there was interested in the database
stuff. However, to our surprise, most of the people there were waiting for our talk instead! Our room filled
quickly. All the seats were taken. People started sitting on the floor or standing up against the walls; they
even had to keep the doors open, and several had to listen from outside in the hallway. In the end, it was the
most exciting presentation I’ve ever been involved in.
Since then, I’ve known the need for information relating to API design is real. The memory of that pres-
entation encouraged me whenever I began losing motivation while writing this book. It helped to remind me
that the rules for proper API design that we had discovered needed to be documented. These rules, though
based on the knowledge spread across common design books, are highlighted and expanded upon in this
book, because designing APIs has its own specific demands.
API Design Is Different
The reason why the existing design books are not enough lies in the fact that designing a
framework or a shared library is a more complicated task than designing an in-house system.
Building a closed system, such as a web application running on your own server with access to
a private database, feels like building a house. Some houses are small, some are big, some-
times they’re skyscrapers. However, in all cases, a house has one owner at a time and the
owner is in charge of making changes. If necessary, the owner can change the roof, replace
windows with new ones, build new walls inside rooms, pull down existing ones, and so on.
nPROLOGUE
xviii
0973-7 FM.qxd 6/26/08 11:25 AM Page xviii