Wild Webmink

At the end of my testimony in the recent Oracle v Google trial in San Francisco, Judge Alsup asked me to explain what an API is. My answer aimed to simplify the answer for a general listener while remaining recognizable to most programmers. Here’s what I said.

The Java source code of OpenJDK usefully follows a layout convention. Up front of each file is a copyright and license statement. After that come a sequence of definitions of the various standard functions that complete the Java programming language. Together, a set of related definitions comprise a class library.

Each of those definitions comprise three parts. There is a function declaration, which defines the name of the function and the order and data types of the parameters used by the function. After that is a comment block with a summary of the specification for the function, tagged to allow it to be automatically harvested by a tool called JavaDoc. Finally there is the body of the function itself, the code which actually does the work of the function.

When a programmer uses the function in a program elsewhere, she lists just the function declaration and parameter list along with an indication of where to find the implementation of the function. Then when she calls the function, she uses the function name.

So what is the API? Although the term is also used in the software industry to mean the more general use of APIs as well (especially for REST applications), the clue is in the word “Interface”. An API is not the code that actually makes the function happen, nor is it the specification for the function. Those only appear in the class library source code.

The API is the part that appears both in the library source code and in the program where the function is used. It’s the interface to the library code used by an application. The API is the common ground; the handle by which the program holds the library; the glue holding linked code together.

Neither is a single Java function in that class file an API. The API is the set of exposed function declarations that provides an interface for the application programmer to the full class library. Other definitions I’ve seen – and were made in the courtroom – left open the possibility that an “API” was in some way the software itself. But it’s not – it’s just the interface between the application programmers code and the code in the library.

I’m sorry if that all sounds obvious. I discovered that there are plenty of people who don’t find it obvious at all that an API is an interface to some shared code for use by an application programmer and not the software which the programmer is trying to connect with. Hence the name.

Filed under: Java | Tagged: API, Copyright, Java |