Minimal API v. Convenience

Question

I am trying to design the interface that will be used internally for my application. Following Google's example, I strive to reduce public API clutter. However, there are some convenience methods that are defined in terms of the minimal methods. What factors should I consider as I seek a balance between convenience and tidiness?

Google example: in HashBiMap (doc):

Why does BiMap have no getKeyForValue() method?

We did think about it (Doug Lea even half-jokingly suggested naming it teg()!). But you don't really need it; just call inverse().get().

Google Collections FAQ

An example of this on the Set interface: add() and remove() are minimal methods, whereas addAll() and removeAll() are for convenience. addAll() could be implemented in terms of add(), so it's not really giving the client new capabilities for working with a Set. But it does clean up client code.

I have considered making a Utility class that would include more convenience methods. But then I'm getting away from OOP, and I have to include the object being operated on as an argument in every call. Although I guess that follows the example of Java's Collections class.

Answer 1

I'd definitely supply the additional APIs whenever there's a chance that the class could (even if it doesn't today) implement that API in a more efficient manner than the client. (For example, Set.removeAll().) And in general I'd supply the additional APIs whenever it cleans up client code.

Could you provide an example of a Google API not providing a seemingly-useful convenience method in favor of having the client make multiple calls?