Paradoxes of API Design

From APIDesign

Current revision

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?

The Chapter 14 contains a note about the importance of trust in the APIDesign. 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.

Reputation

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. bbq pits smokers

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)

Keeping a Promise

There seems to be a significant shift in the way people treat their promises these days. In the MiddleAge, when two knights agreed to rendezvous in Paris after spending ten years on battlefields, they had no choice other than to be at the designated place at the designated time. Otherwise, there would be no chance that they would ever see each other again. The MiddleAge promise could last years.

Nowadays, when you want to meet with someone, you simply negotiate the approximate date and an hour of the meeting and phone the other to confirm validity and settle details. Mobile phones are the root cause of modern people being able to break their original promises!

This affects how the whole society behaves and also how (lightly) many developers treat their promise of BackwardCompatibility.

Promises for Days to Come are as Good as None

In the context of the MiddleAge comparison, does it make sense to believe a contemporary developer promising: Our project is in a development stage, but once we reach version 1.0 we'll keep compatibility?

Tracy Chapman explain it all with her song If Not Now... saying that a promise declared “for days to come is as good as none.”

If you are thinking about developing an API in stable way, which you should, commit to it now, during the first release. There is no reason to wait. Otherwise, you are at risk of not keeping your own promises.

What drives me mad is that some people are even proud of doing that! In one useless conversation, while trying to convince people to stick to their previous promise, I heard the claim that, If there is a rule that says I should waste my money on something, then I am personally quite willing to ignore it and even congratulate myself for doing so.

I have the feeling that nothing illustrates the current state of our society better than this quote. People are not willing to keep a promise if it’s even slightly inconvenient.

Where Trust Matters

However, there are still certain areas where promise and trust are more important than profit. I have a few friends working for various banks as stock dealers, where they all work with promises. If they want to make a deal, they call another dealer, negotiate the price over the phone, and as soon as they say “Done,” the deal is made.

Of course, no money is transferred yet. That is the work of the back office and is delayed by a few days. During that time, the deal might fall through and the bank might be tempted to cancel it. However, I have not heard about this ever happening. Even if the bank stands to lose money on the particular transaction, there is always a much higher cost: loss of trust. Because all the operations among the dealers are based on mutual trust, if you break your promise once, rumors spread and nobody is going to do business with you anymore. No bank wants to risk that.

Although I might be wrong, I see APIDesign as another place where trust is more important than cost savings. The contract between the designer of an API and the API’s users is built on mutual trust. Breaking that trust is the last thing you want to do, as that can only help you lose your biggest asset: the users of your API.

That is why it’s more efficient to spend a few bucks more to implement a compatible extension to your API, than to seek the most cost-effective solution at the expense of good relations with your users.

Still, in light of the erosion of promises in our modern society due to mobile phones, it’s safer to eliminate “future” promises, replacing them with real and immediate actions. Those who care can produce good APIs without that exception anyway. If people want to make promises, they should do so immediately.

Promising heaven in the future doesn’t count.

The InvisibleJob

Chapter 14 describes that supervising the development of an API is a difficult task. First of all, a good API architect has to be like a Cassandra:

• always seeing possible failures
• always knowing what might go wrong in the future
• always proclaiming warnings of danger

Supervision is especially needed when design is done in a group. The better the architect you are working with, the further into the future the architect needs to be able to see. However, this creates a problem that makes the task particularly tricky. People only take notice when something goes wrong:

• when customers become upset by incompatibilities
• when they refuse to migrate to a new version
• when then switch to competitive offerings

However, if everything works as it should, then nothing happens, and it’s difficult to present nothing as a big success. The situation is comparable to that of security agencies. Until a plane is hijacked and destroyed, nobody likes the work of security agents. People complain about the security checks at airports, which seem complicated and unnecessary.

Without a catastrophe, it all seems to be overkill. However, after the disaster it’s too late to fix anything.

Boosting up GraalVM Security

As such, I am always thankful for situations like the one during my fifth year duty at OracleLabs. When you can predict future problems, address them and then a hacking attack proves you were right, then you deserve to be called an architect, I believe!