REST in Peace

“REST is simple.”
— Someone who never built an API used by more than 3 people.

Let’s fix that.

This blog explains REST, RESTful APIs, controllers, HTTP methods, status codes, validation, auth, pagination, and all the interview traps, but in a way your brain won’t rage-quit.

What Is an API? (The Zomato Analogy 🍔)

You don’t walk into Zomato’s kitchen and shout:

“HEY DATABASE, GIVE ME BIRYANI!”

You use the menu.

That menu is an API.

API = Contract

• You ask in a specific format

• You get a response in a specific format

• You don’t care how the kitchen works

Frontend 🤝 Backend
They communicate politely. No screaming. No direct DB access.

REST — Not a Framework, Calm Down 😤

REST = Representational State Transfer

❌ Not a framework
❌ Not a library
❌ Not a tool

✅ An architectural style

REST says:

“Here’s how your API should behave, not how your code should look.”

Core Idea (Remember This Forever)

Everything is a resource, and you operate on it using HTTP verbs.

What Is a Resource? (Spoiler: Not a Verb)

A resource is any “thing” worth naming:

• User

• Order

• Product

• Invoice

• Your hopes and dreams (/dreams/failed)

Each resource has:

• URI → /users/10

• Representation → JSON / XML

❌ Bad

/getUserById
/createOrder

✅ Good

/users/10
/orders

If your URL sounds like a function, REST just cried a little.

REST API vs RESTful API (Yes, There’s a Difference)

🔸 REST API

• Uses HTTP

• Might use GET/POST

• Might ignore REST rules

• Still calls itself “REST” (bold move)

🔸 RESTful API

• Follows REST constraints

• Resource-based URLs

• Stateless

• Correct HTTP methods

• Proper status codes

👉 All RESTful APIs are REST APIs
👉 Most APIs in the real world are… REST-ish

And that’s okay. Interviews still want the theory 😉

REST Constraints (Explained Like a Human)

1. Client–Server

Frontend and backend are in a long-distance relationship.

Frontend:

“Give me data.”

Backend:

“Here. Don’t ask how I got it.”

No emotional dependency. Clean separation.

2. Statelessness (THIS GETS ASKED A LOT)

Server does NOT remember you.

❌ Bad (Stateful)

Server: I remember Sarah logged in yesterday

✅ Good (Stateless)

GET /orders
Authorization: Bearer <JWT>

Every request brings its own identity proof.

REST APIs have trust issues. And that’s healthy.

3. Cacheable

Server should say:

“You can cache this”
or
“Don’t you dare cache this”

Cache-Control: max-age=3600

Performance goes 📈
Backend sleeps better 😴

4. Uniform Interface (The Heart of REST ❤️)

Rules:

• Use nouns, not verbs

• Use HTTP methods correctly

❌ Bad

POST /createUser
GET /getAllUsers

✅ Good

POST /users
GET /users

If your URL reads like English grammar homework, rethink it.

5. Layered System

Client has no idea if it’s talking to:

• Load balancer

• API Gateway

• Microservice

• Server behind another server behind another server

Ignorance is bliss.

6. Code on Demand (Optional, Rare, Weird)

Server can send executable code.

Almost nobody uses this.

You can mention it in interviews and sound smart 😎

Controllers — The Security Guard 🚨

A Controller is the entry point of your API.

It:

• Accepts request

• Validates input

• Calls business logic

• Returns response

Controller Pseudo-Code

GET /users/{id}
  user = userService.getUser(id)
  return 200 OK with user

❌ Controller should NOT:

• Talk to database

• Contain business logic

• Panic

If your controller knows SQL, it’s doing too much.

Clean Architecture (The Holy Trinity)

Controller
   ↓
Service (Business Logic)
   ↓
Repository (DB)

Why?

• Easier testing

• Cleaner code

• Interviewers nod approvingly

HTTP Methods (Memorize This Table 🧠)

Idempotent = Calling it 10 times feels the same as once.

DELETE is emotionally detached.

Status Codes — Speak HTTP Fluently

✅ Success (2xx)

• 200 OK

• 201 Created

• 204 No Content

❌ Client Errors (4xx)

• 400 → Your request is nonsense

• 401 → Who are you?

• 403 → I know you, but no

• 404 → Doesn’t exist

• 409 → Conflict (duplicate data)

💥 Server Errors (5xx)

• 500 → I messed up

• 503 → I need a break

Never return 200 OK with "error": true.
That’s emotional manipulation.

Exception Handling (Don’t Trauma Dump)

❌ Bad

return stack trace
return exception message

✅ Good

{
  "errorCode": "USER_NOT_FOUND",
  "message": "User does not exist",
  "traceId": "abc-123"
}

Use global exception handling.
Your API is not a diary.

Validation — Where It Belongs

• Controller → Syntax validation

• Service → Business validation

POST /users
  if email missing → 400
  if email exists → 409

Validation is a team sport.

Pagination, Filtering & Sorting (Real-World Stuff)

GET /users?page=2&pageSize=10
GET /users?role=admin
GET /users?sort=createdAt_desc

If your API returns 1 million records, it hates you.

Authentication & Authorization 🔐

REST is NOT secure by default.

Security comes from:

• HTTPS

• JWT

• OAuth2

• API keys

JWT Flow (Simplified)

1. Login

2. Get token

3. Send token with every request

4. Server validates token

5. Trust issues resolved

Stateless ✔️
Scalable ✔️
Interview-approved ✔️

REST vs SOAP vs GraphQL (Speed Round)

SOAP is strict.
GraphQL is powerful.
REST is the chill middle child.

Interview Trap Questions (Read Twice)

❓ Is REST stateless?
✔️ Yes — client holds state

❓ Can POST be used for update?
✔️ Yes, but PUT/PATCH preferred

❓ Is REST secure?
❌ No — security is layered on top

✅ Final Mental Model (Tattoo This 🧠)

REST is about behavior, not syntax
RESTful APIs respect HTTP semantics

If your API:

• Uses correct verbs

• Uses correct status codes

• Is stateless

• Is resource-based

👉 You’re RESTful
👉 Interviewer smiles
👉 Life is good