Proximity

From APIDesign

Often there is more than one type of "users" of an API. As 3SidesToEveryAPI explains, there is always at least the [[API] author point of view and API user point of view. But from time to time there may be even more parties involved in design and consumption of an API. Depending on how closely related to the API specification those are, we can group them into API proximity categories.

The most distant group of users for the users of the ClientAPI - e.g. those that make calls into existing API objects, but those that don't implement them. In spite there are differences among this group as well, let's ignore them for now. Let's assume there is always much more users of an API and let's annotate them as N in the following paragraphs.

Zero to N

Some libraries, let's name them simple libraries, have just one implementation. The designer that defines what the API should do also implements it. Obviously, the proximity between the API and the provider of the implementation is almost zero - it is the same person or the same team.

Simple libraries are usually self contained. They combine the API specification together with the implementation. There is no reason, no way to plug into the library and change the way it behaves (for other clients of its API). Examples of such simple library include most of java.util package (with classes like ArrayList or Collections)), or other utility classes like Math class.

Of course, there may be some attempts to re-implement these simple libraries (like GNU Classpath or Harmony show), but those are usually licensing driven efforts, not purely technical ones.

Especially when the simple library is available as open source. It is much easier to contribute back than to fork. If there is some flaw in the library, it seems easier to create an API Patch and donate it back to the simple library owners. In general, there is little to no reason to re-implement simple library APIs.

1 to N

After visiting OSGiCon I can see the value of this category, but yes, I have to admit I feel uneasy. But that is OK, people are supposed to feel uneasy when they have to accept new ideas.

Talk about: ModularLibrary with 1-N and N-M proximities.

M to N

In some cases one needs to have multiple different implementations of some API being used at once. These implementations are being written in distributed development environment, they may not be written against the same version of the library at all. The proximity between the API and the implementations is very weak. As a result trying to mimic the principles used while designing vendor library will not work and even semantic versioning may be too restricting.

In case of modular library the proximity of the API designer and the implementers is almost the same as the proximity of the API designer and the users of the API. This requires the API vendor to prepare evolution plan for both - the ClientAPI as well as ProviderAPI.

As my discussion at OSGiCon revealed, people facing this situation realize the difference between the Many to Many and One to Many and Few to Many cases. However, without having experience with the Many to Many case, they fallback to most obvious solution: Use of abstract classes (or these days interfaces with DefaultMethods). While extending abstract classes with new methods is definitely more compatible than extending interfaces, it can never be 100% safe. The safest solution is to separate API for clients and providers (taken to extreme, while demonstrating all benefits, in the extensible visitor case).

Weak proximity changes everything. An API designer can simplify its life by claiming all providers are close. However sometimes there is just no way around than to admit they are distant. Then the best thing to do is to accept the design style suitable for modular library.

TBD