How APIs Work | distill.md

Q: Are APIs only relevant for developers?

No. While developers write the code that calls APIs, the results affect everyone. Every time you use an app that pulls in data from elsewhere, whether it's a weather app, bank app, or streaming service, an API is at work.

Q: Is an API the same as a database?

No. A database stores data. An API is the interface that lets you interact with that data or with a service that uses that data. Some APIs don't touch databases at all.

Q: Do all APIs work the same way?

No. While REST is the most common, there are other types. GraphQL lets clients specify exactly what data they want. WebSocket APIs maintain persistent connections for real-time updates. SOAP is an older protocol still used in enterprise systems.

Every time you check the weather on your phone, log in with Google, or pay for something online, software is having a conversation behind the scenes. One program asks another for data or an action, and the other responds. This conversation is conducted through APIs, and they’re the invisible plumbing holding the modern digital world together.

The short answer

An API (Application Programming Interface) is a set of rules that lets one piece of software talk to another. APIs are the glue that makes cloud computing work: every cloud service (from AWS to Stripe) is accessed through APIs. When you use an app, the app uses an API to request data or actions from another service: a database, a payment processor, a weather service. The receiving service replies with data in a standardized format. APIs are how different programs share functionality without needing to understand each other’s internal code.

The full picture

What an API actually does

Think of a building code. A contractor doesn’t need to know how every subcontractor works internally: they just need to follow a shared specification: where the wiring goes, how load-bearing walls are structured, what voltage the outlets run on. As long as everyone follows the spec, the pieces fit together. Swap out the electrician, the plumber, or the roofer, and the building still stands.

An API is that shared specification for software. Your app doesn’t need to know how Stripe verifies a card, how Google Maps calculates a route, or how OpenAI generates text. It just needs to send a request in the format the API specifies, and it gets back a response in return.

This separation is powerful. It means developers don’t need to build everything from scratch. They can assemble functionality from specialized services: payment processing, mapping, messaging, AI, and focus on building their own product.

REST APIs: the most common type

Most modern web APIs follow a style called REST (Representational State Transfer). When people say “API” without further explanation, they’re usually referring to a REST API.

A REST API works with a simple model: the client (your app) sends a request, and the server (the service) sends back a response.

The request uses what are called HTTP methods:

GET: Retrieve data. Your app asks for information. “Show me the weather for Barcelona.”
POST: Create new data. Your app submits something. “Create a new user account.”
PUT or PATCH: Update existing data. “Change this user’s email address.”
DELETE: Remove data. “Delete this post.”

Every request goes to a specific URL (called an endpoint). For example, to get weather data, you might send a GET request to something like api.weather.com/v1/forecast?city=Barcelona.

The response typically comes back as JSON: a text format that’s easy for programs to read. It might look like:

{
  "temperature": 22,
  "condition": "sunny",
  "humidity": 65
}

How an API request works

Let’s walk through a real example. You open a travel app and search for flights from Barcelona to London. Here’s what’s happening behind the scenes:

Your app sends a GET request to the travel API’s endpoint, asking for flights between those cities on those dates.
The API receives the request, checks that your app is authorized to make the request (using an API key), and validates the parameters.
The API queries the underlying database or connects to airline systems to find matching flights.
The API formats the results as JSON and sends them back to your app.
Your app receives the JSON, parses it, and displays the flight options on your screen.

This entire conversation happens in seconds, often in less than a second.

Authentication: how APIs verify who you are

Not everyone should have access to every API. Weather data is public, but your bank account data isn’t. APIs handle this through authentication backed by encryption to protect data in transit.

The most common method is an API key: a unique string of characters assigned to each developer or app. Every request includes this key, and the server checks it before processing. If the key is invalid or missing, the request is rejected.

For more sensitive services, APIs use OAuth: a protocol that lets users grant limited access to their accounts without sharing passwords. When you “Log in with Google” on a third-party app, OAuth is what’s happening behind the scenes. The app never sees your Google password. It just gets a token that proves you’re who you say you are.

Real-world APIs you’re already using

It’s easier to understand APIs when you can put names to them:

Stripe: A payments API that lets any app accept credit cards, subscriptions, and invoices. When you buy something on a small e-commerce site, there’s a good chance Stripe processed the payment.
Twilio: A communications API for sending SMS messages, making phone calls, or handling two-factor authentication codes. When an app texts you a verification number, Twilio likely sent it.
OpenAI API: Gives developers access to GPT models for text generation, summarization, classification, and more. Most AI-powered apps aren’t building their own models: they’re calling OpenAI’s API.
GitHub API: Lets tools read and write code repositories, open issues, trigger builds, and automate workflows. Many developer tools are built on top of it.
Google Maps API: Powers maps, location search, and route calculation in thousands of third-party apps, from delivery services to real estate sites.

What you can do with APIs

The modern software ecosystem is built on APIs. No company builds everything from scratch. They assemble functionality from specialized services, connected through APIs.

For founders and developers, this changes what’s possible. Instead of spending months building a payments system, you can integrate Stripe in a day. Instead of building a map from scratch, you use Google Maps. Instead of training an AI model, you call the OpenAI API. Small teams can build products that once required large teams.

Webhooks: when the server calls you

Standard APIs work on a request-response model: your app asks, the server answers. But sometimes you want the server to notify you when something happens: without you having to keep asking.

That’s what webhooks do. Instead of your app repeatedly asking “has anything changed?”, you give the API a URL and say “call me here when something happens.” The server then sends an HTTP request to that URL whenever the relevant event occurs.

Polling vs. webhooks in practice:

Polling (standard REST): Your app asks Stripe every 5 seconds, “Did the payment go through?” Wasteful, slow, and costs you API calls even when nothing has changed.
Webhook: You tell Stripe, “When a payment is confirmed, POST the details to yourapp.com/webhooks/stripe.” Stripe calls you once, exactly when it happens.

Webhooks are how Stripe notifies you of payment events, how GitHub triggers CI/CD pipelines when code is pushed, and how Twilio delivers inbound SMS to your app. They look like APIs in reverse: the server is the client for a moment, and your endpoint is the server.

WebSockets: real-time two-way connections

REST APIs are stateless: each request is independent. WebSockets are different. They open a persistent, two-way connection between a client and a server, letting both sides send messages at any time without the overhead of a new request each time.

This is how real-time apps work:

Chat apps (Slack, WhatsApp web): Messages appear instantly because the connection is always open.
Live collaboration (Google Docs, Figma): Multiple people see each other’s edits as they happen.
Financial dashboards: Stock prices update tick by tick, not when you refresh.
Multiplayer games: Player positions sync in real time.

If REST is like sending letters (one request, one response, connection closed), WebSockets are like a phone call: open until one side hangs up.

MCP: APIs for AI agents

A newer development worth knowing: Model Context Protocol (MCP) is an emerging standard for how AI agents call external tools and services. Where a REST API is designed for human-written code to call, MCP is designed for AI models to discover and use tools dynamically: things like reading files, querying databases, searching the web, or calling other APIs.

Think of it as an API layer that AI agents can navigate without being pre-programmed with every integration. It’s how an AI assistant running in your editor can reach out to GitHub, run a search, or post to Slack, all on its own. MCP is still early, but it points toward a future where AI agents are first-class API consumers alongside human developers.

Why APIs are valuable as businesses

The company providing an API doesn’t just give away free access. Most APIs follow a freemium model:

A certain number of requests per month are free.
Beyond that, developers pay per request or per unit.

This creates a marketplace. Stripe (payments), Twilio (communications), and OpenAI (AI) built billion-dollar businesses by offering powerful APIs that developers can easily integrate. The API is the product.

Why it matters

If you work with software in any capacity, you’ll encounter APIs. Marketers use tools that pull data through APIs. Product managers decide which APIs to integrate. Founders evaluate APIs for their tech stack. Understanding what an API does: and doesn’t do, helps you make better decisions.

For developers, API literacy is fundamental. Reading API documentation, debugging requests, handling errors, managing authentication: these are core skills. And for anyone evaluating a product or service, knowing whether it offers an API (and what that API can do) tells you a lot about its flexibility and integration potential.

Common misconceptions

“APIs are only for developers.” While developers write the code that calls APIs, the results affect everyone. Every time you use an app that pulls in data from elsewhere: your weather app, your bank app, your streaming service, an API is at work. Understanding the concept helps you evaluate tools and services.

“An API is a database.” Not quite. A database stores data. An API is the interface that lets you interact with that data (or with a service that uses that data). Some APIs don’t touch databases at all: they perform calculations, generate images, or trigger actions.

“All APIs work the same way.” While REST is the most common, there are other types. GraphQL lets clients specify exactly what data they want. WebSocket APIs maintain persistent connections for real-time updates. SOAP is an older protocol still used in enterprise systems. Each has different strengths.