Paradoxes of API Design

From APIDesign

Revision as of 13:50, 11 October 2012

Have You Ever Wondered...?

Are you asking now why some API design advices feel so unnatural? Why they are so different compared to the best practices that we learned while working on our small projects or on in-house projects of any size? The reason is that even a small shift in the initial conditions may result in completely opposite advice which may seem paradoxical. However that does not mean such advice is not useful and the chapter 14 describes some of them and explains why adhering to them may be beneficial for any software project.

Video

Paradoxes of API Design is a title of one of the chapters of the Practical API Design book by Jaroslav Tulach. However the title is so strong, that it could even be used as a short summary of the whole area of API design.

When I got a chance to talk at Johannes Kepler University in Linz on Dec 17, 2009 about my favorite topic of API design, I needed to compress my API design knowledge (of at least 400 pages) into 60 minutes. To do so I decided to concentrate on paradoxes. At the end it is exactly the paradoxial things that attract human attention. Check the following video to learn how much attention you are able to pay to API design:

In case you find the discussed topics interesting, consider purchasing the Practical API Design book, get the slides, see the high resolution version of this video. In case you speak Czech, you may be interested in hearing my Ostrava JUG Mar 2nd, 2011 presentation on the same topic. The interest in this presentation grows, I gave yet another one on May 10, 2011 at GeeCON in Krakow. Finally I managed to talk about paradoxes at JavaOne. I guess now I should invent new topic to talk about or at least turn the presentation into a book.

You can also get the sources to play with the factorial sample by yourself:

Code from Arithmetica.java:

public int sumRange(int from, int to) {
    return (from + to) * (Math.abs(to - from) + 1) / 2;
}
 

What is a Paradox?

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.

Money or Trust?

This chapter also contains a note about the importance of trust in the API design. If you broke your promise of BackwardCompatibility once, you repel clients of your API to alternative offerings. It is hard for them to believe that they should once again build their application on top of your API and risk similar problems again.

I compared this situation with the importance of trust among banks and today, in the days of worldwide financial problems, I've found confirmation of my parallel:

Trust is a reciprocal relationship, dependent upon a desire to be considered decent and honourable. Even in the dog-eat-dog financial markets, trust and integrity are matters of self-interest. However amoral you may be, it is in your interest to care about your reputation, because if you behave badly you will not do business with me - or others - on favourable terms again. Trust matters.

Will Hutton, Guardian

Does that mean we need more BackwardCompatibility in our APIs in order to prevent collapse of software industry comparable to the one on financial markets?

--JaroslavTulach 10:19, 30 September 2008 (UTC)