Really like this analogy about API design

Posted by CodingCat on March 4, 2015

Recently I’m reading the book “Practical API Design: Confessions of a Java Framework Architect” by Jaroslav Tulach, the main architect of NetBean

I read an analogy between API design and the Physics of the Universe…really like that, since it covers an important topic on how to ensure backward compatibility and the more important, if you broke it, how to minimize the influence.

“The universe is not constant; it’s always changing. However, it doesn’t change completely arbitrarily. Some rules guide what happens with planets, stars, and other objects. For example,
if someone shifts the horizon and discovers a new star, it’s no surprise that the star is going to be there tomorrow, and the day after tomorrow, and the day after that. Indeed, it can move, it can rotate, and it can even explode. However, the laws of nature guide all this…Once a star is discovered, it is going to be with us forever.”

“APIs are like stars; once introduced, they stay with us forever.”

“Ancient Greeks could identify and observe the movements of the planets, all the way to Saturn and Jupiter, and thus define the planets of their “known” universe. However, although they tried to explain the reasons behind the planetary movements, they weren’t successful according to our current standards…This continued during the Renaissance, when Nicolaus Copernicus proposed the heliocentric system and Johannes Kepler discovered his three laws describing the trajectories and speed of planets on their path around the sun…This discovery enriched the known universe by providing a very precise explanation of “what.” However, nobody knew “why”! It took until 1687, when Isaac Newton provided an explanation of Kepler’s laws, and introduced the notion of a physical force. This not only explained why Kepler’s laws held true, but also started a magnificent expansion of the known universe, because physics could explain nearly everything happening between objects of the known universe, thanks to Newton’s laws.”

“All seemed well until the end of the 19th century…The accumulating evidence that something was not quite right helped Albert Einstein to discover his theory of relativity, which provided an enhanced understanding of the universe, including objects moving with very high velocities. In fact, Einstein’s theory is an extension of Newton’s: when objects move reasonably slowly, both theories yield the same result.”

“The library gives mankind an interface to the “known” universe. Ancient Greeks would be using version 0.1 of the library, which would only enumerate the planets and their names. It’s clearly not a very rich API, but for some users and for some time, it may be enough…the universe 0.1 library was found insufficient because Kepler really wanted to understand the rules for the motion of planets. Therefore, the imaginary god of this paragraph gave him an update called universe 1.0. This version of the library could provide the space coordinates for each planet at a specified time, while the original functionality provided by the Greeks would stay the same and would continue to work…However, users are never satisfied, and the physicists weren’t either. That is why our imaginary god had to help Newton release a new major version called universe 2.0. Not only did this version provide information about the actual force of gravity between the sun and each planet, but also a handy set of subroutines to calculate forces, acceleration, and speed of the objects in space, not just limited to planets.”

“The latest version of the universe library now really faces the problem of no longer being easily backward compatible, because the new idea introduced into it is that everything the previous physicists did, including Newton, was slightly wrong! However, even such a radical change is manageable in backward-compatible mode. Only very high velocities are in danger of incorrect results. These velocities are much higher than Newton and his predecessors could measure, and therefore, although there was an incompatibility, nobody was able to prove an inconsistency in the previously performed measurements, or to prove that the behavior of the universe library had changed”

The last paragraph shows, even you found you have to sort of break the backward compatibility, you still limit the change within the minimum range