Understanding APIs — The Bridge Behind Every App

So if you’ve landed on this blog, then probably one of these reasons brought you here.

Maybe you want to understand what an API (Application Programming Interface) actually is.
Or maybe you’re curious about the foundational magic behind apps — like where does all this data actually come from?

There could be many other reasons too.

But if we combine all of them into one simple thing, then maybe it just means this:

You’re a curious person — someone who likes to stay self-prepared and figure things out on their own.

Before We Dive Into APIs

Before we go into the details of APIs, let’s first look at their real-world applications.

Like:

Are they actually being used somewhere?
Or are we just torturing ourselves again by studying this only to follow the syllabus? 😅

Real-World Examples You Might Have Seen

Recently, you must have seen things like:

“I built an AI SaaS — now you can track all your different orders in one single platform just by connecting your accounts.”

Or maybe something like:

“You can even build your own crypto exchange by interacting with validators.”

Let’s Think of a Simple Scenario

Imagine this.

You’re using an app, and the company is showing you a dashboard or presentation.

All the data is stored on their server.

Now obviously, in that presentation, you want the latest real-time data, right?

So whenever you click a button, your app basically tells the server:

“Hey, the user is requesting this data — send it to me.”

The server then:

Authenticates the request
Processes it
Sends the required data back

So… What Exactly Is an API?

If I explain an API in one simple word, think of it as a mediator.

It takes the message:

From here → to there
From there → back to here

In technical terms, it acts as a bridge between the client and the server.

But Is That All?

Now the question is:

Is an API just a way for a client and server to send requests and responses?

The answer is:

Yes… that’s it.

But don’t underestimate that “just.”

This is the powerful mechanism that helps everything run smoothly:

from a simple todo app
to massive e-commerce platforms

The Interesting Part

Now here’s something interesting.

If every app can talk to its server, just like we humans talk to each other, then have you noticed something?

When humans communicate, we have:

different languages
different vocabulary
different grammar

That’s why we chose a common global language so we can communicate efficiently, no matter which corner of the world we’re in.

Apps Have Languages Too

In the same way, apps also follow different protocols.

You can think of these protocols as:

rules
structure
grammar

But in this blog, we’ll focus on one of the most famous and commonly used API styles:

REST (Representational State Transfer)

And trust me —

you’ve already been using it without even realizing.

What is REST?

REST (Representational State Transfer) is an architectural style.

That means it is a set of rules or conventions that define how communication should happen between the client and the server.

Think of REST Like an Agreement

You can think of REST as a kind of agreement between two parties.

For example, imagine two people deciding:

“We’ll talk in English, and whenever I ask for something, I’ll ask for it in a specific format.”

Both people understand the rules of communication, so the conversation becomes clear and efficient.

That’s Exactly What REST Does

REST works in a very similar way.

It defines how clients should request data and how servers should respond so that communication stays structured, predictable, and easy to understand.

In simple words:

REST is basically an agreement on how communication should happen between the client and the server.

🍽️ Analogy — The Restaurant One (Classic but Gold)

Imagine you’re in a restaurant.

Let’s map the roles:

You → Client (browser or mobile app)
Kitchen → Server (where the data and logic live)
Waiter → REST API

How the Interaction Happens

You don’t walk straight into the kitchen.

Instead, you give your order to the waiter in a specific format:

“I’d like one paneer butter masala.”

The process then looks like this:

The waiter takes your order
The waiter communicates it to the kitchen
The kitchen prepares the dish
The waiter brings the dish back to you

The Waiter Also Follows Some Rules

Just like in a real restaurant, the waiter operates under certain rules:

Orders must be taken in a specific way
Some items are available from the kitchen, some aren’t
The response comes back in a defined format

So What Does This Mean for REST?

That’s basically what a REST API does.

It acts as the middle layer that:

receives requests from the client
communicates with the server
and returns the response in a structured way

🔑 The 4 Main REST Actions (HTTP Methods)

In REST APIs, communication between the client and the server happens through HTTP methods.

These methods define what kind of action the client wants to perform on the server’s data.

Here are the four most commonly used HTTP methods:

HTTP Method	Meaning	Real Example
GET	Request data from the server	Fetch a user’s profile
POST	Send new data to the server	Create a new account
PUT / PATCH	Update existing data	Change a password
DELETE	Remove data	Delete an account

Quick Way to Remember

Think of it like basic operations you perform on data:

GET → Read data
POST → Create data
PUT/PATCH → Update data
DELETE → Remove data

These four actions are often called CRUD operations:

C → Create
R → Read
U → Update
D → Delete

And almost every modern web application uses these operations when interacting with APIs.

🌐 URL Structure — “Routes” in Express

Here I’ll take a few route examples that we developers often write.

These examples follow REST conventions.

// All of these follow REST conventions

app.get('/users', getAllUsers)        // get all users
app.get('/users/:id', getUserById)    // get a specific user
app.post('/users', createUser)        // create a new user
app.put('/users/:id', updateUser)     // update a user
app.delete('/users/:id', deleteUser)  // delete a user

Notice the Simple Pattern

If you observe carefully, there is a very clear pattern behind REST APIs.

Noun → Resource

Examples: /users, /posts, /orders
Verb → HTTP Method

Examples: GET, POST, PUT, DELETE

The URL represents the resource, while the HTTP method represents the action.

A Small REST Rule

REST encourages developers to avoid putting verbs in the URL.

❌ Not REST-friendly

/getUser

✅ REST-compliant

GET /user

The idea is simple:

Let the HTTP method describe the action, and let the URL represent the resource.

📦 Request and Response Format

So by now we’ve understood how to make requests in a clean way, but we still haven’t talked about something important.

What does the data we send with the request or receive in the response actually look like?

Is there a specific format for it, or is there no format at all?

The Most Common Format — JSON

In REST APIs, data usually travels in JSON format.

Here’s an example of a response from this endpoint:

GET /users/1

{
  "id": 1,
  "name": "Arjun",
  "email": "arjun@example.com"
}

This response simply returns the data of a specific user.

How This Looks in Express

If you’ve worked with Express, you’ve probably written something like this many times:

res.json({ id: 1, name: "Arjun" }) // this is a REST response

Here, the server is sending data back to the client in JSON format, which is the standard way REST APIs usually communicate.

🔁 Stateless — An Important Rule

One of REST’s golden rules is that every request should be complete on its own.

This means the server doesn’t remember what you asked for earlier.
Every time you make a request, you need to send the full context along with it.

For example:

a token
a user ID
or other required authentication details

Analogy

Imagine visiting a doctor who has no record of your medical history.

Every time you visit, you have to explain everything again from the beginning.

A REST server works in a very similar way — it’s intentionally a bit “amnesiac.”

And surprisingly, that’s actually a good thing.

Because it helps keep the server:

more scalable
simpler to manage
easier to distribute across systems

That's why when you log in, your app stores a token — and sends it with every request so the server knows who you are.

So the next time you write app.get() in Express — you're not just writing a route. You're following a globally accepted convention used by millions of apps worldwide. That's REST.

🤔 “But Wait — Do You Have to Follow REST?”

No. Not at all.

Even if you ignore REST conventions and write an API like this:

app.get('/users', (req, res) => {
  // Sent a body in GET — Express will still allow it
  const data = req.body // technically this will work
  res.json({ msg: "yep, it worked" })
})

app.patch('/users/:id', (req, res) => {
  // Only fetched the user in PATCH — this will also work
  const user = await User.findById(req.params.id)
  res.json(user)
})

app.delete('/users/:id', (req, res) => {
  // Created a new user in DELETE — this will still work
  const newUser = await User.create({ name: "Arjun" })
  res.json(newUser)
})

…it will still work.

The server will send data.

The client will receive it.

And no error will magically appear.

Where Problems Start ?🤔

The real problem appears when you’re not working alone.

Imagine a new developer joins your team.

They see this:

DELETE /users/1

Naturally they assume:

“This will delete the user.”

But in reality, your code is creating a new user there.

Now:

they’re confused
you’re confused
and the client is confused 🤯

Another Real-World Problem

Imagine a frontend developer using your API.

They send a body with a GET request.

But many HTTP clients and browsers silently strip the body from GET requests.

So what happens?

The data disappears
No error shows up
And you spend three hours hunting a bug

So What Exactly Is REST Then?

REST isn’t a strict rule.

It’s more like an agreement.

And agreements are only followed when they actually make things easier for everyone involved.

So the real question becomes:

Why did REST become the hero?

Before REST — There Was SOAP

Before REST became popular, developers mostly used SOAP (Simple Object Access Protocol).

The word “Simple” was in the name — but the experience was anything but simple.

To make a single request, you often had to:

Manually write an XML document
Wrap an RPC call inside it
Send the whole thing inside a SOAP envelope
Deliver it to a specific endpoint using POST

Documentation Was… Huge

When companies like ReadMe and Salesforce launched their early APIs, the documentation sometimes came as:

400+ page PDF manuals 😅

Not exactly beginner-friendly.

Enter REST (Year 2000)

In 2000, Roy Fielding — one of the co-authors of the HTTP/1.1 specification — introduced REST in his PhD dissertation.

His idea was refreshingly simple:

Keep the same URL, just change the HTTP method.

Example:

GET /posts   → fetch posts
POST /posts  → create a new post

Same URL.

Different intent.

Clean and readable.

Why Developers Loved It

Developers who were tired of SOAP’s complexity quickly started shifting to REST during the mid-2000s.

And today, REST has become one of the most widely used API architectures on the web.

The Real Reason REST Conventions Exist

REST conventions aren’t followed just to make the API work.

They’re followed so that:

other developers
your teammates
and even your future self

don’t go crazy trying to understand the system.

Good conventions make collaboration possible.

And REST is one of those conventions. 😄

📡 Status Codes

Think of it like this:

When a waiter takes your order to the kitchen and comes back, they don’t just bring the dish.
There’s also an implicit message with it.

For example:

“Here you go, this is your order.” ✅
“Sorry, that dish isn’t on the menu.” ❌
“The kitchen caught fire today, nothing’s coming out.” 💀

HTTP responses work the same way.

Along with the data, you also get a 3-digit status code that tells you what happened with the request.

📊 Categories — There Are 5 Families

Range	Meaning	Vibe
1xx	Informational	“Yeah, I’m listening.”
2xx	Success	“Done, here you go.”
3xx	Redirection	“Not here, go there.”
4xx	Client Error	“You messed up.”
5xx	Server Error	“My fault.”

In practice, developers rarely deal directly with 1xx and 3xx, so most of the time you’ll focus on:

2xx → Success
4xx → Client errors
5xx → Server errors

🧑‍💻 Status Codes You’ll Use Daily (with Express)

✅ 2xx — Everything Worked

res.status(200).json({ users }) // data fetched successfully
res.status(201).json({ user })  // new resource created (after POST)
res.status(204).send()          // action done, nothing to return (after DELETE)

❌ 4xx — Client Made a Mistake

res.status(400).json({ error: "Invalid input" })      // wrong data sent
res.status(401).json({ error: "Login first" })        // not authenticated
res.status(403).json({ error: "No permission" })      // logged in but not allowed
res.status(404).json({ error: "Not found" })          // resource doesn’t exist

💥 5xx — Server Made a Mistake

res.status(500).json({ error: "Something went wrong" }) // server crash or bug

🧠 Quick Intuition

You can remember them like this:

2xx → Everything is good
4xx → Client mistake
5xx → Server mistake

Status codes help both developers and applications understand what happened without even looking deeply into the response body.

🤯 401 vs 403 — This Confuses Almost Everyone

This is a very common point of confusion when working with APIs.

Status Code	Meaning	Simple Explanation
401 Unauthorized	Authentication required	“First tell me who you are.”
403 Forbidden	Access denied	“I know who you are, but you’re not allowed in.”

Quick Interpretation

401 → Token is missing or invalid
403 → You are authenticated, but you don’t have the required role or permission

Real Example

// 401 — no token sent
if (!req.headers.authorization) {
  return res.status(401).json({ error: "Token not found" })
}

// 403 — token is valid but user isn't an admin
if (user.role !== 'admin') {
  return res.status(403).json({ error: "Admin access required" })
}

⚖️ 200 vs 201 — Another Thing People Often Ignore

Another small detail that beginners often miss is the difference between 200 and 201.

app.get('/users', (req, res) => {
  res.status(200).json({ users }) // data fetched → 200
})

app.post('/users', (req, res) => {
  // new user created → use 201 Created, not 200
  res.status(201).json({ user })
})

Most beginners return 200 for POST requests as well.

Technically it will still work.

But according to REST conventions, if a new resource was created, the correct status code is:

201 — Created

🫖 The Legendary Status Code

There’s actually a legendary HTTP status code:

418 — “I’m a Teapot”

This started as an April Fool’s joke added to an RFC in 1998.

The idea was simple and hilarious:

If you send a request asking a teapot to brew coffee, the server should respond with:

418 I'm a teapot

The joke came from an experimental protocol called:

HTCPCP — Hyper Text Coffee Pot Control Protocol

Example request:

BREW /coffee HTTP/1.1

And the server replies:

418 I'm a teapot

Even though it started as a joke, the status code still officially exists in the HTTP specification.

Many developers love using it as a fun Easter egg in APIs or error pages. 😄

🧾 Conclusion

If I had to summarize this entire blog in one paragraph, it would be this:

APIs act as a mediator between the client and the server.
REST is an agreement that defines how this communication should happen.
HTTP methods tell us what action we want to perform, and status codes tell us what actually happened.

Together, all of this powers a system that runs inside almost every app in the world — right now, as you’re reading this.

One Thing to Remember

Whenever you write something like:

app.get()
res.status(201)
or create a clean route like /users/:id

you’re not just using Express (or any similar framework).

You’re following a globally accepted convention used by millions of developers around the world.

These aren’t small details.
They’re the foundations on which real-world applications are built.

Before You Go 😄

If you found this blog helpful, share it with that one friend who’s still writing routes like:

/getUserDataPlease

Until Next Time

Till then, we’re off to brew a new topic — and you keep sipping your coffee. ☕

We’ll meet again on another day, probably while enjoying another cup of coffee.

Command Palette