APITypes
From APIDesign
(New page: As TheAPIBook's Chapter 3 argues, there are much more types of an API than ''just'' signatures of classes and methods. Some of them were already discussed in TheAPIBook itself, but...) |
(Dependencies are important API) |
||
| Line 1: | Line 1: | ||
As [[TheAPIBook]]'s Chapter 3 argues, there are much more types of an API than ''just'' signatures of classes and methods. Some of them were already discussed in [[TheAPIBook]] itself, but as our understanding of this topic is growing everyday, this page contains additional and more recent observations about nature of API types. | As [[TheAPIBook]]'s Chapter 3 argues, there are much more types of an API than ''just'' signatures of classes and methods. Some of them were already discussed in [[TheAPIBook]] itself, but as our understanding of this topic is growing everyday, this page contains additional and more recent observations about nature of API types. | ||
| + | |||
| + | |||
| + | == Dependencies == | ||
| + | |||
| + | Not many APIs can live alone, without support from other parts of the system. As each library, also APIs have own environment, which defines what needs to be available around to allow the API to function properly. Each user of the shared library needs to recreate proper environment, that means to satisfy library dependencies, before the API can be used. This implies, that the ''dependencies of a library'' form an important API of the shared library itself. | ||
| + | |||
| + | These dependencies may not even be visible in external signatures! They may only be needed during the runtime, internally, still changing them constitutes an API change. Imagine, that users of your API are using your library in some version and it works fine with just plain JDK. Suddenly, in newer release, you decide to change the library internals and depend on some other library, for example [[wikipedia::Jakarta_Commons|Jakarta Commons]]. That immediately means every user, who migrates to new version of your library, needs to include a version of [[wikipedia::Jakarta_Commons|Jakarta Commons]] in own application as well. This may or may not be a problem, however this is quite an externally visible change. | ||
| + | |||
| + | As the Chapter 3 defines APIs as everything that is externally visible, it makes sense to include ''shared library dependencies'' into the family of various types of APIs. In spite the fact, that it is very hidden kind of API, it is in fact one of the highest level kind and the API that we deal with the most during our day to day work. | ||
| + | |||
| + | --[[Special:Contributions/192.9.112.196|192.9.112.196]] 10:47, 16 June 2008 (UTC) | ||
Revision as of 10:47, 16 June 2008
As TheAPIBook's Chapter 3 argues, there are much more types of an API than just signatures of classes and methods. Some of them were already discussed in TheAPIBook itself, but as our understanding of this topic is growing everyday, this page contains additional and more recent observations about nature of API types.
Dependencies
Not many APIs can live alone, without support from other parts of the system. As each library, also APIs have own environment, which defines what needs to be available around to allow the API to function properly. Each user of the shared library needs to recreate proper environment, that means to satisfy library dependencies, before the API can be used. This implies, that the dependencies of a library form an important API of the shared library itself.
These dependencies may not even be visible in external signatures! They may only be needed during the runtime, internally, still changing them constitutes an API change. Imagine, that users of your API are using your library in some version and it works fine with just plain JDK. Suddenly, in newer release, you decide to change the library internals and depend on some other library, for example Jakarta Commons. That immediately means every user, who migrates to new version of your library, needs to include a version of Jakarta Commons in own application as well. This may or may not be a problem, however this is quite an externally visible change.
As the Chapter 3 defines APIs as everything that is externally visible, it makes sense to include shared library dependencies into the family of various types of APIs. In spite the fact, that it is very hidden kind of API, it is in fact one of the highest level kind and the API that we deal with the most during our day to day work.
--192.9.112.196 10:47, 16 June 2008 (UTC)
Follow
