Practical API design

Here are my notes while reading Practical API design, by Tulach

pg 9:

The point of software engineering cluelessness is to enable the programmers to know less and still achieve good results.

pg 34-35:

I’ve met a lot of people who thought that an API ends at the signature of a class or method. Whatever happens behind it is “implementation,” and these details don’t belong to the API at all. I am guilty of thinking in this way as well. […] Compatibility means that you can replace a piece of the system with its newer version and the system will continue to work as it used to. The observation that “things will work” is the most important constraint of compatibility. This is influenced by the internal implementations of methods deep below the signature level. If a method claims to return a non-null value in one version, then changing it to return null is in fact an incompatible change, because this change can be observed from the outside and negatively influences the component’s users.

Conclusion: Add to function/method signature, return type also.

 pg 35:

Only if the behavior of a component remains unchanged can its users cluelessly replace versions of the component in their final application. Only then can they trust that the functionality will not be compromised by upgrading to a newer version. That is why this book will treat behavior of components as an API.

How can I define behaviour of components on a procedural php software?

What makes a good API: Comprehensibility, Consistency, Discoverability, Simple Tasks Should Be Easy, Preservation of Investment

pg 36

Wide Definition of APIs As is probably clear by now, the definition of an API stretches far beyond a simple set of classes and methods, or functions and signatures. The API, in the sense useful for the clueless assembly of big system components, ranges from simple text messages to complex and hard-tograsp behaviors of the components themselves. Just imagine what a mess you can cause by arbitrarily changing database or XML schemas or by redefining the meaning of WDDL, REST, or IDL services. These all fall into the API category and deserve to be designed with evolution in mind.

Definition: The API ranges from simple text messages to complex and hard-tograsp behaviors of the components themselves.

pg 37

Beauty belongs to the world of art, while software engineering is, well, engineering. The primary goal of engineering is to produce working systems. The fact that deep in our minds we have the old Greek heritage, the feeling that if something is correct, it also has to be beautiful, should not distract us from the main goal: designing APIs that are easy to use, widely adopted, and productive. An engineering approach needs an objective way to measure the quality of its products. We need to formulate this for each API to measure the extent that a given objective is satisfied.

We have to find a way to measure api quality!

pg 40

The users of the API are its jewels. Their work has a right to be respected and admired.


Cluelessness: the ability to assemble applications from modular pieces, while knowing just as little about the individual pieces as possible.

lost process…. now at page 122 and did write down any notes. That was bad.

amoeba effect



The actual behavior of the library will change its shape like an amoeba changes its shape.

A Rule of Thumb

Code Against Interfaces, Not Implementations

Found in many books lately.

Comments are closed.