Re: [xmlvoc] API - 3 choices

[Lars Marius Garshol <larsga@garshol.priv.no>]

* Patrick Durusau
| 
| So, for the first round on defining API we have:
| 
| 1. The interface (calling conventions) by which an application program
|    accesses operating system and other services.  An API provides a
|    level of abstraction between the application and the kernel (or
|    other privileged utilities) to ensure the portability of the code.

Instead of "kernel", which tends to imply "kernel of operating
system", I would say "library" or "module". Also, the bit about
"portability of the code" is kind of strange. What was that part of
the sentence meant to convey? It now sounds like portability from one
platform to another, but I suppose something along the lines of using
abstraction to make the internals of two parts of a program
independent of one another is better.

We should probably make up our minds on whether a CORBA/RMI/RPC/SOAP
interface counts as an API. It's distributed, like a protocol, but
otherwise exactly similar to an API.

BTW, if we use stuff from FOLDOC we should check the copyright status
on FOLDOC and consider how to give them credit.

  <URL: http://wombat.doc.ic.ac.uk/foldoc/link.html >

| 2. An API is an Interface which is used for accessing an application
|    or a service from a program. An API makes it possible to use
|    programs from within programs, therefore it is the foundation for
|    modular systems with clearly defined Interfaces between separate
|    components. In a way, an API can be regarded as the local
|    equivalent of a Protocol, because it is used for the same purposes
|    and defines the same things (the possible interactions between
|    components, and the data that is exchanged while
|    interacting). However, traditionally APIs are used for Interfaces
|    on one computer, while Protocols are used for distributed scenarios.

This one is quite good, but I think it is perhaps a bit too didactic
for our purposes.
 
| 3. A language and message format used by an application program to
|    communicate with the operating system or some other control program
|    such as a database management system (DBMS) or communications
|    protocol. APIs are implemented by writing function calls in the
|    program, which provide the linkage to the required subroutine for
|    execution. Thus, an API implies that some program module is
|    available in the computer to perform the operation or that it must
|    be linked into the existing program to perform the tasks.

This one I am not happy with. It says "language and message format",
which is too broad, and "function calls", which is far too narrow.
Other than that it's quite good, but those "mistakes" are crucial.
 
| I prefer #1 mainly because it avoids the details given in #2 and #3.

I second that.

-- 
Lars Marius Garshol, Ontopian         <URL: http://www.ontopia.net >
GSM: +47 98 21 55 50                  <URL: http://www.garshol.priv.no >