Let’s Make a Contract: The Art of Designing a Java API
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 a very similar operation. Don’t do this.
Keeping your API minimal is another way to make it easy to use. This reduces both the concepts to be learned and its maintainance costs. Once again you can find examples breaking this simple principle in the standard Java API. Optional has a static factory method of(object) that creates an Optional wrapping the object passed to it. Incidentally, using factory methods instead of constructors is another valuable practice since it allows greater flexibility: Doing so you can also return an instance of a subclass or even a null when the method is called with illegal arguments. Unfortunately Optional.of throws a NullPointerException when invoked with null, something unexpected from a class designed to prevent NPEs. This not only breaks the principle of least astonishment — another thing to consider when designing your API — but required the introduction of a second method ofNullable returning an empty Optional when called with null. The of method has an inconsistent behaviour and, if implemented correctly, the ofNullable one could have been left out.
Other good hints that could improve your API are: break apart large interfaces into smaller pieces; consider implementing a fluent API, for which, this time, Java Streams is a very good example; never return null, use empty collections and Optional instead; limit usage of exceptions, and possibly avoid checked ones. Regarding method arguments: avoid long lists of them, especially of the same type; use the weakest possible type; keep them in consistent order among different overloads; consider varargs. Moreover, the fact that a good API is self-explanatory doesn’t mean that you shouldn’t document it clearly and extensively.
Finally, don’t expect a to write a great API first time. Designing an API is an iterative process and dogfooding is the only way to validate and improve it. Write tests and examples against your API and discuss them with colleagues and users. Iterate multiple times to eliminate unclear intentions, redundant code and leaky abstraction.
