What is an API?

Commonly when writing patent applications, I find it difficult to define terms such as API, program or method. Therefore, I found the following discussion in a summary judgement order of Oracle vs. Google interesting.

Conceptually, an API is what allows software programs to communicate with one another. It is a set of definitions governing how the services of a particular program can be called upon, including what types of input the program must be given and what kind of output will be returned. APIs make it possible for programs (and programmers) to use the services of a given program without knowing how the service is performed. APIs also insulate programs from one another, making it possible to change the way a given program performs a service without disrupting other programs that use the service. APIs typically are composed of “methods,” also known as “functions,” which are software programs that perform particular services. For example, a programmer might write a software program method A, which calculates the area of a room when given the shape and dimensions of the room. A second programmer then could write a program method called B, which calculates the square footage of an entire house when given the shape and dimensions of each room. Rather than reinventing a new way to calculate area, the second programmer could simply write an instruction in B, “for each room, ask program A to calculate the area; then add all of the return values,” using, of course, real programming language. As long as the second programmer knows what A is named, what type of “arguments” A must be given as inputs, and what return A outputs, the second programmer can write a program that will call on the services of A. The second programmer does not need to know how A actually works, or is “implemented.” There may in fact be multiple ways to implement A — for example, different ways to divide an oddly shaped room into geometric components — and the first programmer may refine his implementation of program A without disrupting program B.

A method must be defined before it can be used. A method can be “declared” (i.e., defined) in a programming language such as Java by stating its name and describing its argument(s) and return(s) according to syntax conventions. Once a method has been declared, it can be documented and implemented. Documentation is not code; it is a reference item that provides programmers with information about the method, its requirements, and its use. An implementation is code that actually tells the computer how to carry out the method. Often, as in the example above, multiple implementations are possible for a given method.

In object-oriented programming, methods are grouped into “classes.” A class file typically contains several methods and related data. Classes, in turn, are grouped into “packages” known as API packages. Whereas a class generally corresponds to a single file, a package is more like a folder or directory providing an organizational structure for the class files. A given API package could contain many sub-packages, each with its own classes and sub-classes, which in turn contain their own methods. These elements generally are named and grouped in ways that help human programmers find, understand, and use them. A well developed set of API packages, sometimes called a “class library,” is a powerful tool for software developers; as such, it can help attract developers to a particular platform.

The specification for a class library — much like the specification for an automobile — is an item of detailed documentation that explains the organization and function of all packages, classes, methods, and data fields in the library. The class library specification for a given software platform, sometimes called the “API Specification” is an important reference item for programmers. In order to make effective use of the APIs, a programmer must be able to find the portion of the specification describing the particular package, class, and method needed for a given programming task.