Simple-to-understand answers to complex questions
Explain like I'm five: what is an API?
Recently I was reading this article about a big court case between google and oracle.
In it, they were trying to explain the concept of an API to the court. Some of their analogies did not go over very well!
From the article:
Eric Schmidt sought to describe APIs and languages using power plugs as an analogy. Jonathan Schwartz tried his hand at explaining with “breakfast menus,” only to have Judge William Alsup respond witheringly, “I don't know what the witness just said. The thing about the breakfast menu makes no sense.”
Schwartz’s second attempt at the breakfast menu analogy went much better, as he explained that although two different restaurants could have hamburgers on the menu, the actual hamburgers themselves were different—the terms on the menu were an API, and the hamburgers were implementations.
No one bothered to challenge Schwartz’s apparent belief that hamburgers are commonly featured on breakfast menus, as he had already moved on to confusing the jury on another front: the operating system GNU, which is a pearl of the free software community.
So basically, how would you explain what an API is better than Eric Schmidt?
I do basically understand what an API is, but I don't think I could explain the concept to anyone else, and I'm sure there are plenty of nerds around these parts, so I thought it might be a fun if someone else wants to take a crack at it.




Have you ever tried to tell someone how to do things over a telephone? It's hard, because you have to explain every little thing. And you can confuse people by giving lots of instructions that don't matter but leave out facts that really DO matter. Like... try explaining a pizza! You might say 'pepperoni' and 'cheese' and 'onion' but someone who didn't know how to make a pizza might leave out the crust, giving you onion and cheese on pepperoni slices.
But what if had a code? Some way of telling people over a phone that "I need this and this and this done?" That way, you wouldn't have to tell them exactly what to do, you could just say "I need you do to this thing to this object" and get it done. Like, if I'm ordering pizza on the phone, you can just ask for a pepperoni pizza, and they can deliver you a pepperoni pizza.
That's an API. An API doesn't explain how you do things, it just explains how you ask for something to be done. And if the person on the other end of the telephone has to change how things work on the fly, you don't need to worry about why, as long as you know. If the oven goes out and they need to use a microwave, or if they need to deliver with a motorcycle instead of a car, that's not your problem, because you're still getting a pepperoni pizza.
And remember to say 'please!'
That is an excellent analogy because it makes perfect sense to clueless me.
(85% off topic, but it's a great story: as a businessman traveling the barely-former Soviet Union in the 90's, my dad was often the first American many people there had ever met. A Russian family hosting him decided to make American food and settled on pizza—I think they literally looked it up in a dictionary.)
They served it for breakfast. It was cold and topped with horse meat.
He was a good guest and ate it with effusive praise. When I've asked about the taste, he just says darkly, 'It was horse pizza.'
~whenAPIgoeshorriblywrong~)
A program with an API will happily do what you tell it to do. API doesn't know if what it's doing makes sense. All it has is a set of paramaters and an urge to cook pizza.
Think that you have a secret or a complex recipe for something that a lot of people need but have no idea how to make (or even if they do, they're not sure if they can do it correctly themselves). A chef working on a gourmet recipe seems fine for this.
But everybody needs a recipe adjusted to their own needs. (if you're lactose intolerant you'd like lactose free milk, or if you're on a healthy diet and would like olive oil instead of regular vegetable oil , you would need to specify this to the person doing the complex work for you behind the scenes) Basically even though you know what you want and you're relying on the chef (the API) to make it for you, there some things that the chef would like to come from you to describe the optional or variable things he's going to add.
An API provides a service with a description of what the user needs to give to get what he wants, while hiding from him how it is made exactly. It's useful because our chef can perfect his technique and then provide it to everyone who needs it instead of everyone trying to make their own dishes and failing miserably at the first or second try. Suddenly most people realize they're pretty happy receiving a hearty meal of high quality and don't need to really make it themselves.
(Although I feel everyone should learn how to cook, the point is not everyone needs to know how an API works, they perhaps simply require what it provides)