Esoteric terminological query -- APIs

["Haas, Guy" <ghaas -at- selectica -dot- com>]

OK, gang.  I suspect that a pretty small subset of us deals in 
documenting Application Programming Interfaces.

 [For those who have been following TECHWR-L for some while, this
  IS the same set of documents I set about single-sourcing, using 
  FrameMaker conditional text, text insets, and variables.  It worked
  pretty well, but does require discipline.]

I'm documenting APIs for our product, and there are three flavors
of API:  one for C, one for COM, and one for Java.  Each flavor 
has its own manual, but the introduction chapter and the installation
chapter is basically duplicated across all the manuals, and 
occasionally I need to make statements about the set of all three.

But C is a language, Java is a language, and COM is a ..., well, it's
the Component Object Model.  

Much of the actual invocation of functions/methods through the 
COM model is done from programs written in Visual Basic, but it is not
limited to VB. COM is not a protocol, like TCP/IP.  It is a defacto 
standard, not an NIST standard. It is like CORBA (Common Request Broker 
Architecture) -- an agreed-upon way of doing things.

I'd like a "handle" I can use to refer to this set of three
"ways to access the system".  

In the case of the C API, any language that can create calls that are 
compatible with the C language calling mechanism can call functions of 
the API. The description of the calls by which the API is documented 
are C call statement prototypes. Each call sends a set of arguments to
a server and receives a response back that is either a complex data
structure or a diagnostic error structure. This version of the API 
is not object oriented.  

I can't (accurately) talk about the three "language interfaces"
because COM is not a language.  I can't talk about the "three
architectures", because nobody refers to the C calling mechanism
as an "architecture".  Let's not even THINK about calling it
the "three protocols".  Most readers see "protocol" and think
"data comm".

The Java API is object oriented. Essentially for each call
in the C API, there is a class in the Java API that is instantiated
and populated to create an argument object and then the program 
makes a call to pass that to the server, receiving a complex 
data structure or a diagnostic error structure. The description 
of the classes and their methods is very much like a JavaDoc of 
the classes.

The COM API is not now object oriented, but might become so.
Its description is in an IDL (Interface Definition Language)
form, showing which parameters are input, which are output,
which are both. Its behavior now is much like that described for
C, but is likely to change to be more like that discussed for
the Java API.

Has any of you ever had to address this sort of a problem, where
there are multiple APIs that provide entree to a system/product
from a family of different protocols/mechanisms/language-milieus?

--Thanks for any guidance you can offer,
  Guy K. Haas         gkhaas -at- usa -dot- net or ghaas -at- selectica -dot- com
  Software Exegete in Silicon Valley


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Learn how to develop HTML-based Help with Macromedia Dreamweaver!
Dec. 7-8, 2000, Orlando, FL -- $100 discount for STC members.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Your web site localized into 32 languages? Maybe not now, but sooner than 
you think. Download ForeignExchange's FREE paper, "3 steps to successful 
translation management" at http://www.fxtrans.com/3steps.html?tw.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.