Conceptual surface

From APIDesign

The term conceptual surface has been coined by Tim Boudreau during our talks about API Design. It describes the amount of concepts one needs to understand when dealing with an API. Conceptual surface metric is a very useful way to measure complexity of an API.

API vs. Implementation

The primary rule comes from Chapter 6 of TheAPIBook called Code Against Interfaces, Not Implementations: make sure to distinguish between API and implementation! API is supposed to act as a facade hiding the gory implementation details. The fact that something is implemented by ten different implementation classes doesn't mean all of them have to be exposed to users of the API!

Don't mix API and implementation in one package or (if you do) make implementation private so it is not visible in the javadoc. When you split API and implementation into separate packages, consider using FriendPackages accessor so the API package has a priviledged access to the implementation when it needs it. Discourage people from using implementation by making it package private, or in case of Java Modular system by exporting only API package outside of your module.

APIvsSPI

Another common advice when it comes to separating APIvsSPI is to make sure the classes in the ClientAPI part (e.g. the conceptual surface of the API) doesn't reference the service provider part (SPI). This advice optimizes for the common case where the number of people making calls into the API (e.g. using the ClientAPI part) is an order of magnitude bigger than those providing implementation of services (e.g. ProviderAPI). Also the service provider part is often more complicated and could scary the cluelessness out of newcomers.

References

Beware of Leaky abstractions and LeakingCulturalContext.