Redundance in API

Redundance in API’s

Look at any reference manual on API’s there is a lot of “redundance”.

Take for example the CImage library documentation of the CImg class which you can find here:

http://cimg.eu/reference/structcimg__library_1_1CImg.html

It is seems clear to me that a good deal of this documentation can be condensed into a small set of general principles from which the existence of the API functions can be deduced.

This is easy to see in an example:

bool	is_sameX (const CImg< t > &img) const
	Test if image width is equal to specified value.
bool	is_sameX (const CImgDisplay &disp) const
	Test if image width is equal to specified value.
bool	is_sameY (const unsigned int size_y) const
	Test if image height is equal to specified value.
template<typename t >
bool	is_sameY (const CImg< t > &img) const
	Test if image height is equal to specified value.
bool	is_sameY (const CImgDisplay &disp) const
	Test if image height is equal to specified value.
bool	is_sameZ (const unsigned int size_z) const
	Test if image depth is equal to specified value.
template<typename t >
bool	is_sameZ (const CImg< t > &img) const
	Test if image depth is equal to specified value.

There is an obvious pattern above: what goes for the X axis also goes for the Y axis and the Z axis.

Yet to try and articulate this principle is very difficult for your average programmer.

Another problem that comes to mind is that we can have a more or less deep explanation for the patterns of the API. A deeper explanation will be able to have a larger “scope” (influence more API functions).

The problem is not at all trivial, and I do not expect any quick solution.

It might be that instead of just generating a set of API’s specifications from a set of basic principles, there are a set of principles that can conflict and that it’s a matter of balancing the forces from various principles: it could be a constraint satisfaction problem under optimizations.

In any case the redundance of API is not a bad thing per se, as the API designer is supposed to make life easy for the API user.

I close this note by stating that I do not expect to see an extremely reductionist solution to the design of API: It might well be that what passes off as a good set of API today looks quite unsatisfactory ten years from now.