Apparently an API is a hamburger.

That’s according to Sarah Jeong’s fascinating talk at APIStrat, anyway. Jeong is an enterprising reporter who covered the Oracle vs. Google case in 2015. At issue in this case: did Google infringe on Oracle’s intellectual property by implementing the Java API for the Android operating system? A still more important question: could API specifications be considered protected intellectual property, given the inherently public nature of an API?

The case was decided by a lay jury and a judge to whom computer programming was an entirely new concept. So a good part of the trial required witnesses to explain what an API actually is to the judge and jury. As a result we heard a whole suite of metaphors relating APIs to real-world objects. Perhaps the most memorable one: Jonathan Schwartz, the former CEO of Sun Microsystems, compared an API to a restaurant menu. The menu tells you what’s available, but not how it’s made.

In other words: an API is a hamburger. Whether you’re at a greasy spoon or a five-star steakhouse, when you order a hamburger, you have a pretty good idea what you’re going to get, even if the details differ dramatically.

I really like this metaphor, but it only goes so far. It’s an elegant way to separate the concept of specifications from implementation, and it does a good job of explaining the basic concept of an API to a lay audience. So it’s a good way for an API developer to explain what she does to friends and loved ones.

The problem is that this metaphor doesn’t really capture the transformative potential of an API. If you’re working at a software company and you want to explain to upper management just how much a good API program can help expand the business, the hamburger metaphor doesn’t help you very much. (Especially if upper management is vegetarian.)

So instead of the hamburger metaphor, I like to think of an API as an airport. In just the same way that airports provide a means for people to travel back and forth between cities, APIs provide a means for data to flow back and forth between different software packages. But of course an airport does much more than just shuttle people around from place to place: it opens up new lines of communication, it fosters new tourist industries, it allows businesses to operate on much larger scales. In just the same way that an airport opens new economic horizons for a city or a region, a good API program can help a business or organization operate in an entirely different way.

The airport metaphor is not perfect, since it implies that APIs are big, expensive projects that require huge amounts of maintenance. In fact the opposite is true; in many software projects, it’s possible to throw together a simple API in very short order. Furthermore, the airport mechanism is a little misleading: it suggests that APIs can both serve and consume data at the same time, in the same way that O’Hare airport can both send and receive passengers from Laguardia, and vice versa. That’s hardly ideal, though it’s probably not a significant problem when describing the benefits of an API service to the stakeholders who will be resourcing it.

No metaphor is perfect, but a good one can go a long way in explaining an abstract concept to people who need to understand some key aspect of it. I hope the airport metaphor is a helpful one - but I’m certainly curious to hear of other approaches to describing and selling APIs.

Image courtesy of Armando Ascorve Morales