This is a question that cropped up in conversation recently and seemed like an easy one at first. But as the conversation went on, I realised it’s maybe not as straight forward as I first thought.  We have recorded a short video talking about this topic too – Click Here to hear more.

The Literal Definition

Let’s start with the easy part, the literal definition: API is an acronym that stands for “Application Programming Interface”.

Yes, But What Does That Mean?

Well, an “Application” is basically a computer program.

A program is set of instructions that tell a computer what to do. So, “Programming” is the act of giving the computer a set of instructions to follow.

But what is an “Interface”?

In physics: “A common boundary or surface, such as an oil-water interface”. Maybe this is relevant.

In mathematics: “Given an n dimensional space Ω an interface Γ is a co-dimension 1 object that splits the domain into two distinct regions”. I hardly think that’s helpful, thanks Wikipedia.

In Computer Programming: “A data type that acts as an abstraction of a class”. Is this it? I think it might be. If only I knew what it meant.

In General Conversation: “A boundary where independent systems meet and interact with each other, such as the man-machine interface”. I think this is getting closer.

So, an API is the boundary where one computer program connects to another computer program to feed it a set of instructions that tell the receiving computer program what to do.

But you haven’t explained anything!

All you’ve said is that an API is where one program programs another program at a boundary. The only thing missing from that is for you to “explain” how a boundary is simply an “Interface” between two “Applications” and we are right back where we started.

Let Me Try Again

Forget the literal definition. All definitions end up relying on other terms that need defining, until you either get to an undefined term or a circular reference. Let’s talk about what an API does.

Suppose you have two computers that are each running a different program and you need one to communicate with the other. For example, you have a phone running “Super Mars Weather App” and NASA has a supercomputer running a program called “What is The Weather Like on Mars Today?”. FYI, this example is not as far-fetched as you might think.

The NASA supercomputer is in communication with the InSight Mars lander (via an API of course) and it knows what the weather is like on Mars. Your phone needs to communicate with the NASA computer to get a Mars weather update and display it to you in a pretty format.

Well, if these computers are going to talk to each other, they need to agree on a protocol (language). If I try to talk to you, we need a shared language. If we don’t share a common language, then we can’t communicate. Same for computers.

Technically, an API is the definition of a protocol (shared language). A promise or contract if you will, that if you send instructions in the correct request-format, you can expect to receive a response in a well-defined response-format.

For example, if you say “Fizz” I will reply “Buzz”.

That’s Not How People Use the Term

People are very imprecise in their use of language. Unlike computers, they use words in slippery ways. As Humpty Dumpty said to Alice “When I use a word, it means exactly what I intend it to mean”.

So, technically, the API is the specification of the protocol. But in everyday conversation, people use it differently. They say things like “I am going to connect to the API”.

What they mean is: They are going to interact with a program running on their computer (via the user interface), in such way as to reliably cause their computer to communicate with another computer (using the protocol specified in the API), to send a properly formatted request, which will elicit a response in a well-defined format, that can be understood by the program running on their computer, such that the response can be rendered on the screen, in a way that is useful to the user.

But who wants to say such a ridiculous long-winded sentence as that?

Summary

So, in everyday use, people use the term API to refer to any of the following:

• The technical specification of the protocol (The abstract idea of the API)
• The physical server (or network) they are connecting to (A concrete implementation of the API)
• The network interaction between their computer and the other computer (The act of communicating via the API)
• The user interface on their computer which they interact with, having only a vague understanding of anything that goes on beyond what’s visible on their screen (The API thingummy widget)

Some people get very worked up about the “correct” usage of such terms. But I’m mostly with Humpty. Let’s be precise when we need to be. But, trying to be too precise, all the time, actually makes us less understandable most of the time.  If you would like to find out more about this topic or have a chat with our software team please click here.