Ever Changing Targets

From APIDesign

Have You Ever Wondered...?

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.

How Many People Have to Die?

Recently I got a query from a reader about the How Many People Have to Die? sidebar from Chapter 4. That is OK, I intended this sidebar to be personal, emotional, controversial, passionate and it is perfectly appropriate for it to stimulate questions. This has been expected. That is why, I tried to be as precise as possible. Trying to evoke the same emotions among more than one person is hard, and as such I not only refer to my own personal experience with communism, but the note puts the topic into more general context while comparing it with another example of totalitarism - Nazism. I believe that they are similar with respect to their promises and failures, moreover methods of the latter and their results are more widely known and understood around the globe.

However the recent email exchange made me look at my sidebar again, from a completely new angle and made me realize that I did not express myself clearly enough. To my horror, I even referred to events that cannot make any sense to international reader. I wrote: "...even after forty years later in case of communism, things were no better than before". Why 40 years? Because my cultural context leaked! The reign of communism in my country started in 1948 and ended in 1989, and even after those forty plus something years the world was not at all as promised at the beginning. Makes sense, from my point of view, doesn't it? However I fully understand that my readers need to be quite confused. Sorry, I'd like to apologize for letting my cultural context leak.

What does this have to do with API Design? API is about abstractions. About hiding the gory details of a library behind a facade, behind the API. However, regardless of how much time you spend designing your facade, it can easily happen that the implementation details leak out and users of your API need to face them. Regardless of how much you try, your expectations, your context, your implementation will inevitably be around the corner and waiting to jump out from your API unexpectedly. We can do our best, but there is almost always something left unnoticed. Contexts leak. In case you are describing your life experience, in case you are writing about your project API design experiences, or when you create an API facade over implementation of your library. You will all the time expose more than you should. Get ready for that.

And good luck preventing such leakages!