What is an (Open) API?

My wife asked me what an API is the other day. APIs are clearly all the buzz in Health IT, just ask Don Rucker.

What is an API?  First, let's decode the acronym: Application Programming Interface.  OK, that's a mouthful, I see why we shortened it.  Basically, an API is stuff people use to write programs.

Can you name some early examples of APIs in the IT Industry?  How about POSIX, or the XML Document Object Model.  Depending on what millenium you entered the field of software, even the phrase API can be a bit nebulous.  To a C or Pascal or FORTRAN programmer, it is the collection of functions and procedures that you can call to effect some activity on a computer.  C++ and Java folks will understand it as a collection of classes and associated methods that you can use to do stuff. JavaScript, Python, Ruby, Perl ... every programming language has these things.

A "standard" API is one which is well defined, having a formal specification.  POSIX was great in early years of computing when cross-platform code was a real challenge.  We needed the ability to write the same program and have it be able to be compiled and run on a Unix system, a MacIntosh computer, or an IBM PC or compatible system.  POSIX was limited to operation in a programming environment using the C programming language (it was tightly bound to the C programming language, and used C syntax and conventions in its definition).

Today, we work in a plethora of different programming languages.  I use C, C++, C#, Java, JavaScript, HTML, XSLT, CSS, JavaScript, and a host of other special purpose languages, and when I need an API, I want one that works in whatever language I happen to be using at the time.

An Open API is one in which the standard is readily accessible to anyone who wants to use it.  That isn't to say it was free, just readily accessible ... usually the price of a text book.  But to use it you also had to have access to a compiler to build code, but that wasn't a huge issue for most developers, just already part of the cost of doing business.

The first really "free" API I spent any time with was probably the W3C Document Object Model Release 2 (DOM).  While my computer wasn't free, anything I needed to write code using the DOM was (Mosaic and the specification itself).  But frankly, the text book was still useful to teach me how to use it.  DOM was also one of the first APIs I used that had well defined formal bindings to multiple programming languages, including C++, Java and JavaScript.

My example APIs above are not RESTful, although that is often assumed in the case of APIs in modern discussions about them.  An API could also involve other protocols to access objects and methods, such as SOAP, or CORBA or COM (ActiveX).  These are access protocols to APIs, more than they are APIs themselves.  An API need not be bound to a single access protocol or programming language.  Other protocols can also be used, some involve message passing, and other kinds of exchanges.

Open is another interesting word, especially applied in the context of open standards.  If the information about the API is readily available?  To some, all that is needed is a readily available formal specification, but to others, it must be a specification to which not only access to use, but also access to participate in the development is readily available (which implies access to standards setting processes).  And cost is potentially an issue here. Ownership as well.  Microsoft owns COM and ActiveX.  Are they standards? Maybe by some definitions, but not by currently accepted definitions in many countries.  Personally, I prefer the meaning of open that means a) free, and b) that I have the opportunity to participate in its development if I so choose (although I can accept that might have some costs associated with it).

HL7 Version 2 is a messaging standard, and because it is freely available, might also be considered an open standard.  Is it an API?  I would have to argue that it isn't an API by itself, because it misses an essential feature in its specification, which is the expected behavior.  An HL7 V2 ADT A01 message that is sent to a receiver doesn't have any defined behavior according to the HL7 specification.  It just has a trigger event and a bunch of data, and the receiver is free to deal with it as it sees fit.

The receiver could use an ADT A01 message to register a patient, or it could use it to send a message to a housekeeping system that would cause someone to be scheduled to transfer a patient from admissions to a room, or it could communicate a new admission to a care management system then activated someone at the patient's payer to begin the care coordination process for a patient.  The expected behavior here is implied, but unspecified in the HL7 V2 specification.

However, apply that same message to a use case with behavioral requirements o a system upon receipt, using for example, the IHE PIX or PDQ profiles, and now you have a defined behavior occurring.  The receiving system is expected to behave a certain way.  If you have some IHE background, you'll also be aware that PIX and PDQ have HL7 V2, V3 and FHIR variants.  These are basically bindings of the PIX/PDQ behaviors to various syntaxes using messaging or RESTful APIs.

It's one step removed from a programming language, unless you call writing the message syntax itself a language*.  Formally, it is a language, informally, if you have to write code that way, get a better job.  It is definitely a protocol, and often I can translate a protocol into an API with very little effort. I don't usually write messages directly because the syntax is usually too complicated for me to remember where everything goes (although I can do that with FHIR).

Using the above example, is the Direct Protocol an API?  Kinda, but even less so. I also have to pick bindings for message sending and receiving via an edge protocol (POP, SMTP or MAPI), and also do some weird stuff in ASN1 to do DNS lookups.  The reality is, it might be, but I frankly would never treat it the way I do.

What's my answer?

An API is a formal definition of a programming interface, that defines the types of information to be used, the names of the operations that can be performed in that information, and the behaviors that can be expected, which has a defined way of writing a program that tells a computer how to make (usually cool) shit happen.  The essentials** of how you write the code (given a particular programming language) don't vary.  If network communications are part of the API, the essential content won't vary.

An Open API is one I can freely use.

Open protocols are like open APIs, but the essentials of how you might write the code can vary depending on what other tools you have available.  The network trace of communications won't vary.

For me, FHIR is probably the best, but not only example of what an Open API is in healthcare. Several IHE profiles or HL7 Implementation guides might also be considered, but might also be thought of as Open protocols.

   -- Keith

* I have in fact used telnet to a TCP port to write an ADT message directly to a receiver on multiple occasions.
** By essentials, I mean the interpretation of the program by the computer.  The names might change for variables and such, but the meaning and behavior is always the same.