Do APIs Matter?

By Ervin Varga

The benefits of a proper API are best understood by relating the level of entropy in the software system and its maintainability. The relationship is inversely proportional, i.e. lessening the number of safe assumptions (increasing entropy) reduces the comprehensibility of the system. During maintenance, most effort is spent to understand the code. If we invest energy to make things explicit via APIs, then less time is needed for software engineers to decipher what is going on inside the system. The following citation (see references 2 and 3) nicely correlates the amount of energy we must utilize to perform a useful work (in this instance a computation), hence reduce entropy:

"Landauer’s principle, often regarded as the basic principle of the thermodynamics of information processing, holds that any logically irreversible manipulation of information, such as the erasure of a bit or the merging of two computation paths, must be accompanied by a corresponding entropy increase in non-information-bearing degrees of freedom of the information-processing apparatus or its environment."
—Charles H. Bennett, Notes on Landauer’s principle, reversible computation, and Maxwell’s Demon

We may also extend the above principle to an API, so that an energy invested into increasing the comprehensibility of the system (by building it around APIs) is proportional to the reduction of its abstruseness (entropy). This inevitable leads to more maintainable solutions (as exemplified in the next case study).

Case Study - A System Without a Thoughtful API is Like a Puzzle

Figure 1-1 shows the puzzle (see reference 4), which represents the situation software engineers are very familiar with. In a system where everything is buried inside the code, it is hard to understand how the system works. In some sense, engineers must guess what will be the outcome of a change, rather than altering the source code in a controlled manner. Most of the time, the source code is reflecting the partial snapshot of the overall development context, at the time when the code was produced.

Figure 1-1. Guess what number is missing from the second front door (picture taken from reference 4). This illustrates the position of a software engineer when she/he needs (in the absence of an API) to speculate what will the system do for some set of inputs.

When I give this puzzle to my students they usually came up with multiple answers. Here is one typical set:

• 15 (also the official answer from the book)
• 14
• 22.8

What happened? What is the right result? Let’s see the explanation for each of them to decide.

The Rationale for 15

(2+3) + (1+1) + (4+0) + (1+6) = 18. Here, the digits of numbers from all windows are simply summed together. Therefore, for the second door we get (3+3) + (1+0) + (2+1) + (5+0) = 15.

The Rationale for 14

(|11-40| + |23-16|) / 2 = 18. Here, the result is the average of the sum of the absolute differences of numbers in windows per row (upper and lower). You will also get same outcome with grouping windows per column. Therefore, for the second door we get (|33-50| + |10-21|) / 2 = 14.

The Rationale for 22.8

(23+11+40+16) / 5 = 18. Here, the numbers from all windows are summed up, and divided by the total number of objects on the front of the house (4 windows + 1 door = 5 objects). Therefore, for the second door we get (33 + 10 + 21 + 50) / 5 = 22.8.

Conclusion

Honestly, all answers have a reasonable justification. It might appear that the last one is invalid, as it isn't an integer. However, please notice, that the puzzle just asks for a number (this is how my students usually defend their answer). This is clearly a deficiency in the requirements specification, or more precisely the lack of such a specification.

Another interesting detail is the way that the numbers inside windows are handled. The first solution breaks them apart into digits, while the latter two use them in an atomic fashion. Also, the way numbers are combined is totally different.

This riddle could disappear by an existence of a clear API, as it would unambiguously specify how numbers should be treated individually as well as in a combined fashion. Nothing to be guessed anymore! Investing into a proper API would turn this puzzle into a trivial task. The energy invested upfront would save you from lots of waste later.

This article tries to illustrate from an additional perspective the importance of having well-defined APIs. For a more thorough treatment of the topic you may read my book (see reference 1). The accompanying example (case study) above is using the Puzzle Based Learning approach (please, visit www.puzzlebasedlearning.edu.au), what I successfully leverage in my university courses.

References

1. Ervin Varga, "Creating Maintainable APIs - A Practical, Case-Study Approach", Apress, 2016

2. Charles H. Bennett, "Notes on Landauer’s principle, reversible computation, and Maxwell’s Demon", Studies in History and Philosophy of Modern Physics, www.cs.princeton.edu/courses/archive/fall06/cos576/papers/bennett03.pdf

3. Erik P. DeBenedictis, "Computational Complexity and New Computing Approches", IEEE Computer, December 2016

4. Popular Prakashan, "IQ Challenge", www.popularprakashan.com, 2004