Conceptual surface
From APIDesign
(→API vs. Implementation) |
|||
| (3 intermediate revisions not shown.) | |||
| Line 1: | Line 1: | ||
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]]. | 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]]! | ||
| + | |||
| + | <!-- show example from https://vmmeetup.github.io/2015/ | ||
| + | |||
| + | An API for a multi-threaded, multi-language, multi-tenant, multi-node VM | ||
| + | Jaroslav Tulach, Oracle Labs | ||
| + | |||
| + | Comparing the Interop API before and after cleanup | ||
| + | |||
| + | --> | ||
| + | |||
| + | 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 [[Modular_Java_SE|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]]. | ||
[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]] | [[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Meta]] | ||
Current revision
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.
Follow
