The other day I was talking to a customer about a feature of one of our APIs.  In his view, it needed to be changed, so that the default behaviour fitted in with how his application needed to work.  This reminded me of the principle of least astonishment which simply put says that whenever there is some kind of failure mode, the program should do whatever the user will find least astonishing.  For example, if you are using a word processor, and try to reopen a file off your ‘recent’ list: If the file has been deleted, you would expect a warning dialog telling you that the file could not be found.  A more astonishing response would be for the word processor to explode and disappear, leaving you staring at the desktop.

For APIs, usually the least astonishing behaviour is for API functions to carry on working in the same way from version to version, year after year.  If you look at the Windows API, for example, a function called SetWidget might be supplemented by a function called SetWidgetEx in the next release.  Functions are rarely changed (or even removed), as this would cause existing applications to fall on their faces. Another approach (which we sometimes use in Dialogic) is to allow different options or properties to be set in the application, which change the mode of operation of later function calls.  This modal behaviour should also avoid user astonishment, since existing applications will not change the mode, and will so carry on using the well-known functionality.

In APIs, avoiding astonishment is a key goal, as an API is essentially a long term contract between application and service layer.  Software development can be an expensive process, and modifying an application every time the API is upgraded is not usually an option.