Episode 143: API Design with Jim des Rivieres

Stability

Maintaining API stability is crucial for ensuring backward compatibility and minimizing disruptions for clients. Jim des Rivieres emphasizes that the best APIs are those that remain unchanged, allowing existing programs to function without modification 1. He explains that Java's specific rules for binary compatibility can be complex, but understanding them is essential for evolving APIs without breaking compatibility 2.

The best APIs are the ones that don't change. That allows the clients who have actually written their programs against a particular API, it allows that code to keep running without actually having to be changed.

--- Jim des Rivieres

Jim also highlights the importance of knowing when to create new APIs to avoid accidental crashes when breaking compatibility is unavoidable 1.

   

Evolution

Evolving APIs requires careful consideration of techniques like creating new versions and using abstract classes. Jim discusses the challenges of using Java interfaces, which can lead to fragility when methods are added or removed, and suggests using abstract classes for more flexibility 2. He references Joshua Bloch's book, "Effective Java," which provides guidance on choosing between interfaces and abstract classes to maintain API stability 2.

You actually do much better in a lot of cases to have abstract classes.

--- Jim des Rivieres

Additionally, Jim compares APIs to a cover story in a spy novel, where the goal is to present a coherent narrative to different users while hiding the complexities behind the scenes 3.