What Is an API?

An API (Application Programming Interface) is a promise written in code.

It's a contract that says: "If you ask me this way, I'll answer that way, and I won't change the rules without warning."

Every time you tap a button and something happens on a server you've never seen, operated by people you'll never meet—you're trusting an API to keep its word. That trust, multiplied across billions of requests per day, is what makes the modern Internet possible.

The Word "Interface"

An interface is a boundary where two things meet and interact. Your car's steering wheel is an interface between you and the vehicle's mechanics. You don't need to understand how power steering works to turn left.

APIs work the same way. A weather API lets you request tomorrow's forecast without knowing how the data was collected, where it's stored, or what algorithms predicted it. You just ask. It answers.

The interface hides complexity and exposes capability.

How APIs Actually Work

APIs work through requests and responses. One system (the client) asks for something. Another system (the server) provides it.

When your weather app shows tomorrow's forecast, here's what happened:

1. Your app sent a request to a weather service: "What's the forecast for this location?"
2. The weather service received the request, looked up the data, and packaged it
3. The service sent back a response with the forecast
4. Your app displayed it in a pretty interface

Your app never touched the weather service's database. It never knew how the forecast was calculated. It just asked a question through the API and got an answer.

The Anatomy of a Web API

Most APIs you'll encounter are web APIs—they communicate over HTTP, the same protocol your browser uses. Here's what they're made of:

Endpoints are addresses where you send requests. Like https://api.weather.com/forecast or https://api.stripe.com/charges. Each endpoint does something specific.

Methods say what you want to do:

• GET: Retrieve something
• POST: Create something new
• PUT: Update something that exists
• DELETE: Remove something

Parameters provide details. "Get the forecast" becomes "get the forecast for latitude 37.7749, longitude -122.4194, in Fahrenheit."

Headers carry metadata—authentication tokens, content types, caching instructions.

Request bodies hold data you're sending, usually as JSON.

Response bodies hold data coming back, also usually JSON.

Status codes tell you what happened: 200 means success, 404 means not found, 500 means the server broke.

Why APIs Changed Everything

You don't have to build everything yourself. Need to process payments? Use Stripe's API. Need to send texts? Twilio's API. Need maps? Google Maps API. Each of these companies spent years building infrastructure you can access with a few lines of code.

Systems can specialize. Instead of one massive application, you can build focused services—authentication, payments, notifications, search—each with its own API. They work together without being tangled together.

Implementations can change without breaking clients. As long as the API promise holds—same endpoints, same data formats, same behavior—you can completely rewrite the backend. Nobody using your API will notice.

Platforms become ecosystems. Twitter, Stripe, Shopify, Salesforce—they all became more valuable when developers could build on top of them through APIs. The API turned a product into a platform.

Public, Private, and Partner APIs

Public APIs are open to anyone. GitHub's API lets any developer build tools that interact with repositories. These APIs need excellent documentation, ironclad backward compatibility, and robust abuse prevention—breaking changes affect thousands of external developers.

Private APIs exist inside organizations. Your company's services talk to each other through internal APIs that outsiders never see. These can evolve faster because all the consumers are your own teams.

Partner APIs sit between—shared with specific business partners under agreements, with special access and rate limits.

The API as Promise

The most important thing about an API isn't the technology. It's the contract.

When you publish an API, you're making promises:

• These endpoints will exist
• They'll accept these parameters
• They'll return data in this format
• They'll behave this way
• If we need to change something, we'll give you warning

Breaking these promises breaks trust. It breaks the applications built on your API. It breaks the developers who invested time learning your system.

Well-designed APIs treat their contracts as sacred. They version carefully. They deprecate gradually. They communicate changes clearly. Because an API isn't just code—it's a relationship with everyone who depends on it.

What Makes an API Good

Consistency. If GET /users returns a list of users, then GET /posts should return a list of posts. Patterns should be predictable.

Clear naming. /users beats /u. getUserProfile beats getUP. Names should explain themselves.

Honest errors. When something fails, the error should explain what went wrong and ideally how to fix it. "Invalid request" helps no one. "Missing required field: email" helps everyone.

Real documentation. Show working examples. Explain every parameter. Include sample responses. Document error conditions. An undocumented API is a useless API.

Security from the start. Require authentication. Validate inputs. Use HTTPS. Protect against common attacks. Security isn't a feature to add later.

The Types That Matter

Web APIs are what most people mean when they say "API" in 2024. They use HTTP, return JSON, and power the integrations between applications and services across the Internet.

Library APIs are the interfaces that programming languages and frameworks expose. When you call array.map() in JavaScript, you're using an API—the contract that says "give me a function, I'll apply it to each element."

Operating system APIs let programs interact with the OS—creating windows, reading files, accessing the network.

Database APIs let applications query and modify data. SQL itself is a kind of API.

Hardware APIs provide access to devices—cameras, GPS, accelerometers.

They're all interfaces. They all make promises. Web APIs just happen to be the ones that connect the Internet.

The API Economy

APIs became products.

Stripe's API generates billions in revenue. Twilio's API powers communications for companies worldwide. AWS sells API access to compute, storage, AI, and dozens of other services.

The "API economy" is the ecosystem where functionality is bought and sold through programmatic interfaces. Companies expose capabilities. Developers build applications. Value flows through the connections.

This is genuinely new. Twenty years ago, if you wanted payment processing, you negotiated contracts with banks and built custom integrations. Now you read Stripe's documentation, write a few lines of code, and you're processing payments by tomorrow.

APIs made capabilities composable. That changed everything.