How To Design a (module) API

A description of good design practices when design any APIs with especially closer look to the case of an API based on NetBeans infrastructure is content of this evolving document.

What is a API?
As the reason why API is used is to allow communictation between teams and applications in order to allow separated and distributed development the answer to question what is API shall include everything that influences such kind of development.

The API is everything that another team or application can depend on:

• method and field signatures - communication between applications is usally about calling functions and passing data structures between each other. If there is a change in the names of the methods, in their arguments or in structure of exchanged data, the whole program often does not even link well, nor it can run.

• files and their content - many applications read various files and their content can influence their behaviour. Imagine application relying on the other one to read its configuration file and modifying its content prior to invoking the application. If the format of the file changes or the file is completely ignored, the communication between those applications gets broken.

• environment variables - for example behaviour of cvs can be influenced by the variable CVSEDITOR.

• protocols - opening a socket and being prepared to interpret streams sent there, or putting or reading a data to clipboard or during drag and drop again establishes an API that others can depend on.

• behaviour - a bit harder to grip, but important for the separation as well is the the dynamic behaviour. How the program flow looks like - what is the order of execution, what locks are being held during calls, in which threads a call can happen, etc.

• L10N messages - because the localization to a certain language is usually developed and distributed by somebody other than the person that writes the code, yet both of them have to use the same keys (NbBundle.getMessage ("CTL_SomeKey")), there is inherently a contract between the writer of the code and the translator - an API of sorts.

The important thing with respect to distributed development is to be aware of possible APIs - of possible things other code can depend on. Only by identifying such aspects of own application one can develop it in a way that will not hurt cooperation with seperately developed applications.

web resource:
google video:http://video.google.com/videoplay?docid=-3733345136856180693
book in amzoe The Definitive Guide to API Design (The Definitive Guide) (Hardcover)