97 Things Every Java Programmer Should Know

Chapter 55. Let’s Make a Contract: The Art of Designing a Java API

Mario Fusco

An API is what developers use to achieve some task. More precisely, it establishes a contract between them and the designers of the software, exposing its services through that API. In this sense, we’re all API designers: our software doesn’t work in isolation but becomes useful only when it interacts with other software written by other developers. When writing software, we’re not only consumers but also providers of one or more APIs, which is why every developer should know the characteristics of good APIs and how to achieve them.

Firstly, a good API should be easily understandable and discoverable. It should be possible to start using it and, ideally, learn how it works without reading its documentation. To this end, it’s important to use consistent naming and conventions. This sounds pretty obvious; nevertheless, it’s easy to find, even in the standard Java API, situations where this suggestion hasn’t been followed. For instance, since you can invoke skip(n) to skip the first n items of a Stream, what could be a good name for the method that skips all the Stream’s items until one of them doesn’t satisfy a predicate p? A reasonable name could be skipWhile(p), but actually this method is called dropWhile(p). There’s nothing wrong with the name dropWhile per se, but it isn’t consistent with skip performing ...