An API is a PublishedInterface
to software-based functionality. It's needed because System Calls are often too dependent on machine architecture. APIs abstract system calls. Interestingly, the PosixStandard
regulates APIs, not system calls. Hence even WindowsNt
can be one of the POSIX-compliant OperatingSystems
Some part of the API is also executed by the processor in User Mode, whereas system calls are in purely Kernel Mode.
is an interesting topic, with somewhat different forces than other software design.
What is an API, anyway? What does the abbreviation stand for? How about a WikiSingleVote
-  Application Program Interface
- [x] Application Programming Interface
-  Application Programmer Interface
All three seem to be in use. Application Program Interface, for example, is defined at http://www.oreilly.com/reference/dictionary/terms/A/Application_Program_Interface.htm
, and SearchEngine
s will return hits on the other two.
Do all non-private methods of a type form an "API", or is that considered too small a granularity, such that they can only form part of a bigger API? Need every non-private method be considered part of an "API", or can there be non-private methods that aren't considered part of an "API"? Is there any significant difference between "API" and the "PublicInterface
" or "public protocol" of a type?
The term "PublishedInterface" covers this. "Published" is the next level above "public". I think of an API as a "surface" presented by many packages together. So strive to make the "layers" in your programs as much like APIs as possible, and the application objects between the layers not. -- PCP
The big problem with a lot of published APIs is that what you get is a list of method/procedure signatures and a bit of waffle about what each one itself does. This is sometimes be very useful, which is why OreillyAndAssociates
make so much money. But often one needs more.
Conversely, one strength of components (if used properly) is that they explicitly address the issues of environment and interaction: a complete specification of a component has to include the component's expectations of the environment within which it will be deployed: both
the expectations that clients have of the component and that it has of them. The CatalysisMethodology
has much to say on this subject. -- KeithBraithwaite
It's commenting taken to another level; the purpose of comments isn't to explain what the code does - the code itself should be able to do that - but to explain why it does it the way it does or why it exists in the first place. In the same way, a list of method signatures and synopses isn't going to explain the "why" of an API.
See also NonPublishedPublicInterfacesAreRefactorable