Api Design Theory
Currently there is no API design theory.
|Problems of the current Situation|
Software as is. Typical APIs, like the Win32 API, the Java class library, some programming language runtime library or the TWAIN interface are constructed as parts of software projects, according to certain needs together with their specification and documentation. Although programmers find fault with of these and hundreds of other APIs, the typical reaction of the API builders is "if it works and works according to the documentation, it's ok". When it doesn't work according to specification or works according to undocumented features this is often considered a problem of the documentation. Software is "software as is". Users don't have the right to expect a certain quality, consistency, efficiency, orthogonality or simplicity. They may, of course, vote with their feet. But their choice is limited.
Built on predecessors. Of course, APIs learn from previous versions and add to the feature set of competing products. But just as often idiosyncracies are copied.
Feature creep. Feature lists look good, especially if products are compared to the competition. The quality of implementation is not easily visible and gets no priority. So many features are added without real need.
Incompleteness. Almost always APIs are incomplete in features and in documentation. No-one cares about that. Worse is better. If the projects sells, there is still time to repair inconveniences in the next release or the release after that.
Complexity. Due to the structure of projects, APIs become much more complex than necessary. Programmers working on separate modules follow separate ideas and work independently. Features are added in a patch-work fashion. Functions get additional parameters and parameters start to interact in a non-intuitive way. If necessary, hacks and work-arounds are used - but hardly ever documented.
|Cornerstones of a future API theory|
A future API theory must enable us to tell right from wrong in important software aspects. The goal of such a theory should be to improve overall software productivity. An API theory should allow the user to select the best from various options. There aren't more than one ways to do it, there is only one way to do it right.
Responsibility. Any API must have a clear overall goal statement. The goal definition should enable a outside expert to decide whether a given functionality is to be part of an API or not.
Modelling. If possible, elements of an API should correspond to real world objects and use real world language and paradigms.
Simplicity. Occam applies. There shouldn't be more features, functions, objects, ... whatever ... than necessary. Any unnecessary complexity is a fault.
Efficiency. The implementation of an API should be as time- and space-efficient as possible. It is a fault not to use state-of-the-art algorithms or methods.
Consistency. An API should clearly define its language and reuse existing language as much as possible. Deviations from documentation, positive (undocumented feature) or negative (faulty behaviour), must be considered a fault of the API.
Tolerance. An API should be as tolerant as possible with regard to mishandling.