Paradox
From APIDesign
One can face a Paradox when one hits something unexpected. However there is nothing paradoxial on seeing a paradox. Paradoxes happen naturally. Why?
Knowledge of every individual is limited by some horizon, just like our vision. What is closer to us, can be seen more sharply. What is further, is more fuzzy. What is almost on the horizon is unclear, not well understood. What is behind the horizon is unknown. Still, our experience tells us that there is something behind the horizon. Because from time to time every individual, or mankind manages to enlarge the known world and shift the horizon further. Then, things that have been unseen get in front of the horizon and we may start to explore them.
It is natural for humans to make expectation about the things behind the horizon. To envision how the things behind the horizon are about to look like. There are basically two (extreme) ways to handle this envisioning. Either we can fear the unknown and envision that the world behind the horizon is dangerous (full of lions). In this mode we however are not encouraged to explore such places. It is much easier if we (in contrast to previous attitude) imagine that the unknown world is almost the same as the known one. Just things may be a bit bigger, with higher velocities, but otherwise similar to what we know. With attitude like this it is much easier to undertake a journey behind horizon and explore new creatures.
Often our expectations are matched. Especially when we cross the horizon just slightly. However sometimes, when we discover something really new (like the Michelson experiment), it may contradict our pre-made expectations. It may look like a paradox. However that does not mean the world went insane. It only means that our interpretation of the world is not accurate and we need to create new one (just like Einstein did in response to the experiment).
There is nothing unnatural in seeing paradoxes. Usually that only means we managed to significantly enlarge our horizons. The newer a topic is the more paradoxes one can expect. As such it is of no surprise that there is a lot of unexpected Paradoxes of API Design.
20 API Paradoxes Book
Soon after publishing Kant's Critique of Pure Reason, Kant realized that nobody is able to read it all and he released his Prolegomena to summarize and re-explain in more understandable style the thoughts of his Critique. I'd like my Paradoxes to do the same to TheAPIBook with the hope to attract wider audience to the topic of API design and convince part of them that it is worth to buy TheAPIBook.
The book is now available for download at Amazon US and mirror sites, including Amazon GB. Those who prefer other formats and readers than kindle may take a look at Barnes & Noble site.
The presentation has been delivered many times. Here is a recording of 20 API Paradoxes at JDD Krakow.
