What Is an API, Really

Every app on your phone is quietly talking to a dozen others while you use it. Your weather app does not measure the temperature itself, it asks a weather service. Your ride app does not draw its own maps, it borrows Google's. When you check out on some random online store, that store almost certainly is not processing your card itself, it hands the whole thing to Stripe. All of this coordination happens through one unglamorous piece of plumbing, and it is the single most important idea in modern software.

That piece of plumbing is an API, short for application programming interface. Strip away the jargon and it is just a contract: a defined way for one program to ask another for data or an action, without either side knowing how the other works inside. That last part is the whole magic. You can use Stripe without knowing a thing about how banks settle transactions. The API is the seam that lets software be built out of other software.

The waiter analogy, and where it breaks

The classic way to explain an API is the restaurant waiter, and it is a good start. You sit down, you read the menu, you tell the waiter what you want, and food arrives. You never walk into the kitchen. You do not need to know how the stove works or where they source the fish. The menu is the API. It tells you exactly what you are allowed to order and what you will get back. The waiter is the messenger carrying your request to the kitchen and bringing the result back.

That gets you most of the way. But it hides the part engineers actually care about, which is that the menu is a strict, machine-readable contract. If the menu says you order a burger by writing the word “burger” in lowercase, and you write “Burger,” the kitchen might reject it. APIs are pedantic in a way waiters are not. The precision is the point. It is what lets two programs written by people who never met, in different languages, cooperate perfectly. So let me open the kitchen door and show you the actual mechanics.

Requests, endpoints, and methods

Almost every API you will touch is a web API, which means it works over HTTP, the same protocol your browser uses to load pages. A conversation with a web API has two halves. You send a request, and the server sends back a response. That is the entire dance.

A request has a few moving parts. First, an endpoint, which is just a URL like api.example.com/users/42. Each endpoint is one item on the menu. Second, a method, the HTTP verb that says what you want to do with that URL. The four you will see constantly are GET to read something, POST to create something, PUT or PATCH to update it, and DELETE to remove it.^[1] The beauty of this is that it is a tiny, fixed vocabulary. GET a user, POST a new order, DELETE a comment. Once you know the four verbs, every REST API in the world reads the same way.

The request can also carry headers, which are metadata like your API key or the format you want back, and for POST or PUT it carries a body, the actual data you are sending. If HTTP itself is fuzzy to you, the encryption layer that wraps all of this is worth a detour through our HTTP vs HTTPS explainer, because every real API call today runs over HTTPS.

The response, and the codes that tell you what happened

The server answers with a response, and the first thing it contains is a status code, a three-digit number that tells you how it went before you even look at the data. You have seen 404 Not Found in a browser. That is the same system. 200 means success. 201 means something was created. 400 means your request was malformed. 401 means you are not authenticated. 403 means you are authenticated but not allowed. 429 means you have made too many requests, and 500 means the server itself broke.^[2] Good code checks the status first and reacts accordingly.

Then comes the body, the actual payload, and these days it is almost always JSON.

Why JSON won

JSON, JavaScript Object Notation, is the format nearly all modern APIs use to send data back and forth. It is just text, structured as keys and values, and it looks close to how you would sketch data on a napkin: a user has a name, an id, an email. The reason it beat the older, heavier XML format is not technical elegance. It is that JSON is human-readable and that virtually every programming language can turn it into native objects with one function call.^[3]

That matters more than it sounds. The whole promise of an API is that two programs written by strangers can cooperate. A shared data format that any language parses for free is what makes that cheap. You get a blob of JSON from a Python server, and your JavaScript frontend reads it without anyone agreeing on anything ahead of time except the shape of the data. JSON is the lingua franca, and it is boring, and boring is exactly what infrastructure should be.

REST, and the styles that challenge it

When people say “REST API” they mean an API that follows a set of conventions layered on plain HTTP: use the standard verbs, treat everything as a resource with its own URL, and pass JSON around. REST stands for Representational State Transfer, and it won the web because it is dead simple and it uses the machinery HTTP already gave us for free.^[4] No special tooling, no heavy contract, just URLs and verbs.

REST is not the only game, though. GraphQL lets the client ask for exactly the fields it wants in one request, which solves REST's habit of returning too much or forcing you to make five calls. gRPC uses a compact binary format that is faster for services talking to each other behind the scenes. Each is a different trade-off between simplicity, flexibility, and speed. I dug into when to reach for which in REST vs GraphQL vs gRPC, but for learning the concept and for the majority of public APIs, REST is still the default and the right place to start.

Keys, auth, and rate limits

Once an API is open to the world, two questions become urgent. Who is calling, and how much can they ask for? The answers are authentication and rate limiting, and they are the guardrails that keep a public API from being a free-for-all.

Most APIs identify you with an API key or a token, a secret string you send with every request, usually in an authorization header. It tells the service who you are, lets it check whether you are allowed to do what you are asking, and lets it track and bill your usage.^[5] The key is a password, so you treat it like one. Leak your Stripe secret key on GitHub and someone can move money as you. Real systems layer on OAuth for user-delegated access, but the mental model is the same: prove who is calling before the door opens.

Rate limiting answers the second question. An API caps how many requests you can make in a window, say 100 per minute, and once you cross it the server stops answering and returns a 429 Too Many Requests until the window resets.^[6]This protects the service from being hammered, whether by a runaway loop in someone's code or an actual attack. Well-built clients read the rate-limit headers the API sends back and back off before they get blocked instead of after.

APIs as a product, and as an economy

Here is where it gets genuinely interesting, and where I think most explainers stop too early. For a long time an API was a technical afterthought, a side door onto a product that existed for other reasons. Then a handful of companies flipped it. They made the API the product.

Stripe is the cleanest example. Its entire pitch is that adding payments to your app should take a few lines of code instead of months of work and a bank relationship.^[7] Twilio did the same for text messages and phone calls, turning telecom infrastructure that used to require carrier contracts into a single API call.^[8] Google Maps did it for location. In every case the company took something genuinely hard, wrapped a clean API around it, and sold access. You are not buying software you run. You are renting a capability through an endpoint.

The way I think about it, this is one of the great business ideas of the last two decades. An API-first company sells leverage. Every developer who integrates it is a distribution channel that compounds, because their app carries the API into places its makers never had to sell into. It is why Stripe and Twilio became enormous without a consumer brand most people could describe. The moat is not the code, plenty of people could build a payments processor. The moat is that switching costs pile up the moment thousands of businesses wire your endpoints into their checkout.

This is also why APIs are the connective tissue of the whole software economy. Modern products are increasingly assemblies. You wire together Stripe for money, Twilio for messaging, a maps API for location, an auth provider for logins, and a cloud database for storage, and the thing you actually build is the thin, valuable layer on top. If you have ever set up a project in an IDE and watched it autocomplete a call to some service you have never read the source of, you have felt this. Software is Lego now, and APIs are the studs that let the bricks click together.

What I'd do

If you are trying to actually understand APIs rather than just nod along, do not read more explainers. Call one. Pick a free public API, a weather service or a currency exchange feed, grab a tool like Postman or just curl in a terminal, and send a single GET request. Watch the JSON come back. Change the URL and watch the answer change. That one loop, request goes out, response comes back, teaches you more than any diagram, because the abstraction stops being abstract the moment you see real data land in your terminal.

And once it clicks, you start seeing APIs everywhere, because they are everywhere. Every login button, every embedded map, every “pay now,” every price that updates without a page reload, is an API call under the hood. Learning to see them is learning to see how modern software is actually assembled. It is, genuinely, the seam the whole thing is built along.