This is the first paragraph for the API page on Wikipedia. I love Wikipedia but this is not what I'd want to read:

An application programming interface (API)  is a computing interface which defines interactions between multiple software intermediaries. It  defines the kinds of calls or requests that can be made, how to make  them, the data formats that should be used, the conventions to follow,  etc. It can also provide extension mechanisms so that users can extend  existing functionality in various ways and to varying degrees.[1] An API can be entirely custom, specific to a component, or it can be  designed based on an industry-standard to ensure interoperability.  Through information hiding, APIs enable modular programming, which allows users to use the interface independently of the implementation.

This description is correct and precise of course but also meaningless to someone trying to quickly get a sense of the Thing called API.

Knowing what the acronym stands for is also not very meaningful. You may know the words application, programming, and even interface individually but putting them together doesn't lead to an immediate 'ah I see what it is now'.

So what is an API? Imagine a function. When you call a function in any programming language, you have some input parameters and you have an expected output value. For example if we have a function called sum we may pass in two numbers as input and expect to receive the mathematical sum of those to numbers as the output response.

Calling an API works similarly. You pass in some parameters as the input and expect to receive some output.  The difference between APIs and the function call analogy is that calling an API happens over the Internet. And the response usually contains data that is stored and maintained by the owner of the API.

It's a way of making a precise request to a server. Instead of requesting a webpage (HTML) we're requesting specific data (aka resource).

Why APIs

Since all of the interesting data in the world is spread out over various computers, we need a way for one computer to send a request to another computer for a specific data (e.g. list of books for a user) and receive a response that it can understand. Since the request is sent over the Internet, we use HTTP as the protocol and the response data is usually sent in JSON format. Why do we need this? The requesting clients can build useful functionality using the data it receives from an API call and can display relevant information to a user.

Example: when you use google maps on your phone, all of the maps of the entire country or world are not stored on your phone. Your phone fetches it from somewhere — a google server using google maps API — and display your local streets and directions to you, at the time the data is requested. You know this intuitively because you know that you have to be 'online' to use many applications. These applications need to be able to communicate to some servers over the Internet. API is the name given to this type of interaction.

Programming with APIs

There are number of ways programmers interface with the concept of APIs:

  1. We can call 3rd party APIs from your programs.
  2. We can create our own APIs to give others access to your application's data and 'business logic' (a term that refers to code specific to a given domain, for example banking application would have business logic around account balances, deposits, withdraw, loans, etc.)
  3. APIs can separate our applications into backend and frontend [link]. Where the backend manages the data and logic to access that data. The frontend 'calls' the backend to display useful information and functionality to the user.

The last one is interesting. This implies that frontend and backend development can happen in parallel to some extent, assuming we have decided the details of our APIs. APIs are a contract in that way — 'if you send me a GET request with such and such parameters, I will reply with data structured in this way'.

So as users of a given API how do we know what parameters to send in a request? And how to interpret the response? As a developer of an API how do we advertise the capabilities of our API? This is when API documentation comes in. Most public APIs have their documentation available on the web for others to get a sense of that APIs capabilities. Here are some examples of API documentation:

Goodreads API for getting a list of books by a given author for example -

Twitter API interacting with tweets

Google maps API for getting a map of a specific location

Another tool for API development is Swagger, specifically Swagger editor demo


Now that you have a sense of the essence of this Thing called an API, feel free to ask follow-up questions to anyone who drops this term in casual conversation.