APITypes

From APIDesign

As TheAPIBook's Chapter 3, Determining What Makes a Good API argues, there is 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.

Visual Aspects

The usual consensus is that visual aspects that are presented just to the end user are not part of API of some application. This is usually well justified and correct, especially in multi-platform framework like Java. Programmers that would rely on some library to render a button 8px next to right border, with a certain text painted in dedicated RGB color could be successful with their application on one screen resolution, while horribly fail on small monitors with limited gray scale. Common sense suggests that writing this kind of checks is against good habits of using APIs.

However recently I had an opportunity to face this kind of rendering bug. Stylesheets of this website were reported to be broken on firefox 3.0, while working fine on other browsers and older versions of firefox itself. The text in the navigation and toolbox areas were supposed to be black with yellow background, but for some reason firefox 3.0 was able to render it without the desired background. Some users reported that reading black text on black background is not really pleasant.

I was not sure where is the bug and I asked for help the mozilla guys. To my surprise they reacted pretty quickly, verified that this is behaviour of Opera and other browsers as well and even suggested how to fix my CSS files. Thanks guys, my website is looking much better now. However this leads me to two API observations:

• If I used an API in some version and it used to work, I consider it a bug that it does not work in new releases. I guess many programmers feel the same. And this all applies in some situations even to visual outcomes.
• Even rendering can sometimes become part of API, especially if you accidentally start to render black text on black background, there will be many people who complain about behaviour of your rendering engine.

Still, I'd like to apologize and thank mozilla guys for quick resolution and help. Solving incompatibilities between versions of some product is definitely much easier with such great support that I got as part of 449911 issue. Thanks.

--JaroslavTulach 13:55, 11 August 2008 (UTC)

<comments/>

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.

--JaroslavTulach 10:47, 16 June 2008 (UTC)