Have You Ever Wondered

From APIDesign

Many people want to know, before they start to read a book, whether it can help them solve some problems. That is very likely reason why many books start with have you ever wondered sections. TheAPIBook does not contain such section itself, however that in no way means that there are not problems that it helps solve! You can bet that there is a lot of them! TheAPIBook is a lab journal describing adventures of NetBeans project and as such, it is almost completely stuffed with problem solutions. Here is short have you ever wondered section to demonstrate that.

Have you read many books about design? Have you read some? Do you think you know everything about proper design? Are you asking why bother with yet another design book? The prologue shows you that you should care. Most design books are written for "in-house" development, however with the rise of code reuse caused mostly by proliferation of various open source libraries and frameworks, we are entering world of distributed development. The new coding life style needs slightly different designing approach. After reading prologue, you'll find out that you need TheAPIBook if you want to code software for the 21st century.

Have you ever considered yourself artist when coding? Do you think programming is kind of art? Have you noticed the difference in developing software systems today and twenty years ago? Do you know why people consider ugly solutions wrong? If you ever asked questions like this, the chapter 1 gives you answers that I found after many years of oscillating between feeling like artist and behaving as engineer. Did you ever hopelessly searched for new programmers? We do it all the time and it looks like we are constantly running out of good programmers. But how good a programmers has to be to produce good software? Maybe it is enough if one can code HTML.

Maybe you are asking yourself: "Why should I slow myself down by creating an API? Is not that more work?". In the second chapter of TheAPIBook I describe that overall, it is not more work. Moreover I also reveal that even if you try, you cannot live without APIs. APIs are everywhere, even in in-house systems. In the world of DistributedDevelopment they become inevitable.

Have you ever searched for the root reason why some of APIs you liked more than others? Are those APIs that you liked the most also those most easily usable? I was thinking about this a lot. First of all I broaden the meaning of the term API and let the chapter 3 define what it means an API, explain why and enumerate various APITypes. Then I also look at the basic objective criteria to ensure an API is really good.

Are you afraid of upgrading your favorite application to newer version? I am. Every time I need to upgrade X Window server, I am stressed and ready for problems that almost always appear. Are you asking how this relates to API Design? Easily, the building blocks of our systems which provide some functionality via their APIs (like the X Window server), are expected to evolve and evolve compatibly. It is not hard to produce new version of a framework or library, it is hard to release new version that will remain compatible. This is quite a big difference from in-house software system development and the chapter 4 discusses its implications and the actions we need to take to resolve them.

Do you want to know some simple trick that will help you design better APIs? The chapter 5 gives you one. It is very elementary, but very powerful. It also shows that the object oriented languages of today are not really optimized for API development and that there are many gotchas one needs to be aware of.

Have you ever participated in a flamewar between people who believe API should be full of interfaces and those who believe it is better to use classes? Was the dispute resolved somehow or people just kept their original views? Yes, I've participated in such discussions few times and yes, they never lead to any conclusions. However then I've managed to look at the old code against interfaces advice in new light and things started to make sense. Since then I have eliminated flamewars of this kind almost completely. Probably because the revelation is not only surprising, but also backed by rational reasoning. You can find this all in the chapter 6, plus see application of this rule for Request/Response API Design Pattern.

OK, so you want to prevent object-oriented spaghetti mess by splitting our systems into into independent modular pieces, however I wonder how to glue them together? Are there some good practices for doing so? Yes, there are and the Chapter 7 gives some. For example to glue pieces together you need some injection to configure all individual components to work together. The Chapter 7 builds the understanding for this by starting with the most straightforward and hand-coded solutions and then enhances them to cover injection as provided by Spring Framework as well as latest releases of JDK.

Have you ever subclassed some API class and started to ask yourself: "Shall I override its particular method or just call it?" Or: "Is this method public because external users shall call it or am I supposed to override it?". Chapter 8 brings you answer to such common worries. It analyses the differences between evolution of APIs targeted to different clients, analyses what kind of messages various Java access modifiers carry and gives a recipe to convert a class full of methods with unclear multiple meanings into an API that carries just one, clear message for every developer using it.