What Is an API, Really? | Blog

Series: API · Part 1 of 6 — What Is an API, Really?

🕐 ~8 min read · Beginner friendly

📝 A note on this article · This post is based on my personal study notes. The ideas, learning journey, and understanding are mine — I used AI to help structure and expand them into a proper blog format form.

You open a food delivery app, browse the menu, tap a few items, hit checkout — and half a second later, you see your order confirmed. You didn't think about what just happened under the hood. But in that half second, your app reached out to a completely different computer, somewhere in a data center, asked it a question, received an answer, and updated your screen.

That's an API at work.

You're probably using dozens of them every day without realising it. The weather on your lock screen. The login button that says "Continue with Google." The map that loads inside another app. APIs are the invisible plumbing that connects almost everything in modern software.

But if you ask a junior developer what an API is, the answer is often something vague — "it's like a way to get data." That's not wrong, but it's not enough. Understanding what an API really is — how it works, why it's designed the way it is, and what can go wrong — is what separates developers who use APIs from developers who build systems with them.

This is Part 1 of the Understanding APIs series. By the end, you'll have a clear mental model of what an API is, how the request-response cycle works, and why API design is something worth caring about from day one.

So, What Actually Is an API?

API stands for Application Programming Interface. Let's break that down in plain terms.

An API is a way for two pieces of software to communicate — a set of rules that defines what one system can ask from another, and what it will get back. Think of it as a bridge between services. Without the bridge, each system is an island. With it, they can share data, trigger actions, and work together in real time.

But here's the key word: contract.

When two systems communicate through an API, they agree on the rules. System A agrees to send a request in a specific format. System B agrees to respond in a specific format. That agreement is the contract. If either side breaks it — say, a field gets renamed, or a response structure changes — things break, and they break loudly.

This is why APIs are more than just "a way to get data." They're promises between systems. And like any promise, they need to be made carefully.

Library, API, SDK — Where the Line Is

Before going further, let's clear up something that confuses a lot of developers early on.

When someone says "API," they usually mean a remote API — a service running on a different server that you talk to over the internet. But strictly speaking, the word "API" shows up in a few different contexts:

Library — A package or module you install into your project that solves a specific problem. You call its functions directly in your code. The functions you call are its API — the interface it exposes to you. Think of it like buying a packet of Taco Seasoning instead of measuring out cumin, chili powder, garlic powder, and salt yourself. Someone already figured out the ratios. You just open the packet.

API (Remote/Network-level) — This is what people usually mean. A set of rules and endpoints for communication between systems running on different machines, over the internet. You don't know (or care) how the server is built on the inside. You just follow the rules of the interface. Like a drive-thru window: you look at the menu, say your order into the speaker (the request), and someone hands you a burger through the window (the response). You have no idea how their kitchen is organized. You just followed the window's rules.

SDK (Software Development Kit) — A complete toolkit for building on a specific platform. An SDK typically includes libraries, APIs, documentation, and sometimes tools like compilers or debuggers. Think of a meal kit delivery box — it comes with the raw ingredients (libraries), the seasoning packets (documentation on how to use them), and sometimes a specialized tool like a sauce whisk (platform-specific utilities). The Android SDK, iOS SDK, AWS SDK — these give you everything you need to build for that platform.

For the rest of this series, when we say "API," we mean the remote, network-level kind — a service living on a different server that you communicate with over HTTP.

The Client-Server Mental Model

To really understand how APIs work, you need the right mental model. Here it is:

Imagine you're at a restaurant.

You are the client — a browser, a mobile app, a smart TV, whatever is making the request.
The kitchen is the server — a computer in a data center somewhere that holds your data, runs the business logic, and prepares the response.
The waiter is the API — the rules and interface between you and the kitchen. You don't walk into the kitchen yourself. You use the menu (the available endpoints) and the waiter (the API) to place your order.

Here's how a single cycle works:

Request — The client sends a request to a specific endpoint (like /users/profile), using an agreed-upon method and format.
Processing — The server receives the request, checks who's asking, fetches the right data from the database, and prepares a response.
Response — The server sends back a structured answer: a status code (did it work?) and a body (the actual data).

Once the response arrives, the cycle is complete. The connection closes. Until the client asks again, nothing happens.

This is the request-response cycle, and it's the foundation that everything else in this series builds on.

The Anatomy of an HTTP Request and Response

Most APIs you'll work with use HTTP — the same protocol your browser uses to load web pages. Understanding the core parts of an HTTP message is essential.

Methods — What You're Asking the Server to Do

HTTP methods tell the server what kind of action you want to perform:

Method	What it does
`GET`	Read data. Fetch a user profile, a list of products, etc.
`POST`	Create something new. Submit a form, register a user.
`PUT`	Replace something entirely.
`PATCH`	Update part of something.
`DELETE`	Remove something.

Headers — The Metadata

Headers are key-value pairs that travel alongside every request and response. The user never sees them, but the systems on both ends rely on them heavily. Some important ones:

Content-Type: application/json — Tells the receiver what format the body is in. "The data I'm sending is JSON."
Authorization: Bearer <token> — Your security badge. This is where JWTs or API keys live to prove you're allowed to make this request.
Cache-Control: max-age=3600 — Tells the client it can reuse this response for the next hour without hitting the server again.
X-RateLimit-Remaining — How many requests you have left before the server starts refusing you. When this hits zero, the server returns a 429 Too Many Requests response — sometimes with a Retry-After: 60 header telling your app to wait 60 seconds before trying again. That's where a "You're moving a bit fast — please wait a moment" message comes from.

Body — The Actual Content

The body carries the payload — the real data being sent or received.

For a GET request, there's usually no body. You're just asking. But for a POST request, the body contains the data you're submitting — like a new user's email and password in JSON format.

For a response, the body is what you came for: the user's profile, the list of orders, the confirmation message.

Status Codes — How It Went

Every response comes with a 3-digit status code. A few you'll see constantly:

Code	Meaning
`200 OK`	Everything worked.
`201 Created`	A new resource was successfully created.
`400 Bad Request`	The client sent something malformed.
`401 Unauthorized`	You need to be authenticated.
`403 Forbidden`	You're authenticated, but not allowed to do this.
`404 Not Found`	The resource doesn't exist.
`429 Too Many Requests`	You're hitting the API too fast.
`500 Internal Server Error`	Something broke on the server's side.

API Styles — There's More Than One Way to Build One

Not all APIs are built the same way. The four styles you'll encounter most:

REST — The most common. Uses standard HTTP methods and URLs that represent resources (/users, /orders/42). Stateless, simple, and widely understood. This is what most web APIs use, and it's what we'll spend the most time on in this series.

GraphQL — Instead of multiple endpoints, you have one. The client describes exactly the data it needs using a typed schema, and the server returns exactly that — no more, no less. Efficient for complex frontends, but requires more setup.

gRPC — Built for speed. Uses HTTP/2 and a binary format (Protocol Buffers) instead of JSON. Ideal for internal service-to-service communication in microservices architectures where latency matters.

SOAP — The older standard, still alive in enterprise and banking systems. Uses XML and has strict, verbose contracts. You're unlikely to build with it today, but you might encounter it in legacy codebases.

Each style has trade-offs. Choosing the wrong one for the job creates friction for years. We'll dedicate a full article to REST, and we'll cover when GraphQL or gRPC makes more sense.

Synchronous vs. Asynchronous — A Critical Distinction

Synchronous (Sync) — The client sends a request and waits. Nothing else happens until the server responds. The connection stays open. If the server takes 5 seconds, the client sits there for 5 seconds. That's the loading spinner. Sync APIs are tightly coupled — both systems need to be up and working at the same time.

Asynchronous (Async) — The client sends a message and moves on. It trusts that the system will handle it eventually. The systems are loosely coupled — if the receiver is temporarily down, the message waits in a queue.

Here's a concrete example. Think about placing an order online:

Step 1 — Checkout (Synchronous). When you tap "Place Order," the app makes a synchronous REST call to the checkout service. It needs an immediate answer: Is this item in stock? Is the payment valid? You wait for the response. This is the right call here — you need to know right now.

Step 2 — Everything after payment (Asynchronous). The moment payment is confirmed, the system fires an event: Order_Paid. Your app shows "Order Confirmed" and you're done. But in the background, asynchronously:

The inventory service updates the stock count
The shipping service generates a tracking number
The email service sends your confirmation
Days later, the courier's system hits a webhook on your server to say "Package delivered"

You didn't wait for any of that. The systems handled it in their own time, in the background.

REST and gRPC are synchronous by nature. Webhooks and event queues (like Kafka or SQS) are asynchronous. Real systems almost always use both.

Why API Design Matters More Than You Think

Your API is a product. Its users are other developers and engineers. And like any product, a poorly designed one will frustrate them.

Code changes are relatively safe. You update your frontend or backend, push the change, users get it on the next refresh. Nobody outside your system feels it.

API changes are different. Change a field name — say, username becomes user_name — and every client that calls that endpoint breaks. Your frontend. Mobile apps. Third-party integrations. All of them, immediately, unless you planned for it.

A well-designed API is intuitive enough that a developer can guess how an endpoint works without reading the documentation. It only returns the data that's needed — no more. It doesn't accidentally leak sensitive fields in responses. It handles errors clearly and consistently.

One of the practices that enforces this discipline is API-first development: designing the API contract before writing any implementation code. When the contract is defined first, frontend and backend teams can build in parallel. The frontend team uses a mock server that returns fake data matching the agreed contract. Nobody is waiting for anyone else. And when both sides meet, they fit together cleanly — because they were built to the same spec.

Build the bridge first. Then decide whether it's for pedestrians, cars, or trains.

What's Next

This series will go deeper on each piece we touched on here. Next up: REST — The API Style Everyone Uses — where we'll look at how RESTful APIs are structured, what makes a good resource design, and what HTTP methods actually mean in practice.

→ Part 2: REST — The API Style Everyone Uses

📌 Series overview:

Part 1: What Is an API, Really? ← you are here

Part 2: REST — The API Style Everyone Uses

Part 3: GraphQL: When REST Gets Messy (coming soon)

Part 4: gRPC: APIs Built for Speed (coming soon)

Part 5: API Patterns You'll Actually Use in Production (coming soon)

Part 6: REST, GraphQL, or gRPC: How to Pick (coming soon)