Chapter 09 — REST APIs

Shreyesh kolhe
July 10, 2026

Chapter 09 — REST APIs

Hey everyone! Welcome back to Namaste Computer Networks! 🙏

An API is how two programs talk. REST is the most popular set of conventions for building web APIs — the ones you'll design and consume constantly as a developer. It's not a technology, it's a style: a set of sensible rules that make APIs predictable. If you know HTTP (Chapter 07), REST is mostly common sense with names. Let's formalize it.

What we will cover:

  • What REST is (resources + HTTP verbs)
  • The restaurant-menu analogy
  • Designing RESTful endpoints
  • The REST principles (statelessness, etc.)
  • Good practices: versioning, pagination, status codes
  • Interview Questions

1. What Is REST?

┌─────────────────────────────────────────────────────────────┐
│   REST (REpresentational State Transfer) = a style for web   │
│   APIs where everything is a RESOURCE (a noun), addressed by  │
│   a URL, and acted on with HTTP methods (verbs).             │
└─────────────────────────────────────────────────────────────┘

   The core idea:
     RESOURCES are nouns:   /users, /orders, /products
     HTTP METHODS are verbs: GET, POST, PUT, DELETE

   Combine them → a clean, predictable API:
     GET    /users       → list users
     POST   /users       → create a user
     GET    /users/1     → get user 1
     PUT    /users/1     → update user 1
     DELETE /users/1     → delete user 1

   Once you learn the pattern, you can GUESS any endpoint. That
   predictability is REST's superpower.

2. The Restaurant Menu Analogy

   A REST API is a MENU 📋. It lists what you can order (resources)
   and how. You (the client) place an order; the kitchen (server)
   fulfills it. You don't need to know how the kitchen works —
   just the menu (the API contract).

   The menu is organized by dish (resource), and you specify what
   you want done (the verb): order it (POST), cancel it (DELETE),
   change it (PUT).

3. Designing RESTful Endpoints

   ✔ GOOD (nouns, plural, hierarchy):
     GET  /users/1/orders        → user 1's orders
     GET  /orders/55/items       → items in order 55
     POST /users/1/orders        → create an order for user 1

   ✗ BAD (verbs in the URL — not RESTful):
     GET  /getUser?id=1
     POST /createNewOrder
     POST /deleteUserById

   RULE: the URL names the RESOURCE (noun); the HTTP METHOD says
   the ACTION (verb). Don't put verbs like "get"/"create" in the URL.

4. The Core REST Principles

   1. CLIENT-SERVER   → clear separation; they evolve independently.
   2. STATELESS       → each request carries everything needed; the
                        server stores no client session between calls
                        (identity via token each time). Enables scaling.
   3. UNIFORM INTERFACE→ consistent, predictable resource URLs + verbs.
   4. CACHEABLE        → responses can be cached (GETs especially),
                        thanks to HTTP caching headers.
   5. LAYERED SYSTEM   → client doesn't know if it's talking to the
                        server directly or through a load balancer/proxy.

Statelessness is the one interviewers love — same idea as the System Design and OS series: no per-client state on the server → any server can handle any request → easy horizontal scaling.

5. Good Practices (What Makes an API Pleasant)

PracticeWhy
Use proper status codes200/201/400/404 tell the client exactly what happened
Version your API (/v1/)Change without breaking existing clients
Paginate large listsNever return a million rows; use ?page=&limit=
Use nouns, plural, consistentPredictable, guessable endpoints
Filter/sort via query paramsGET /users?role=admin&sort=name
Return JSON, consistent errorsEasy to parse; predictable error shape
Secure itHTTPS + auth tokens + rate limiting
   A well-designed REST endpoint in action:
     GET /v1/products?category=books&page=2&limit=20
     → 200 OK
     { "page": 2, "total": 480, "items": [ {...}, {...} ] }

6. REST vs Alternatives (Quick Note)

   REST    → simple, resource-based, cache-friendly. The default.
   GraphQL → client asks for exactly the fields it needs (one endpoint).
   gRPC    → fast binary, great for internal service-to-service.

   REST remains the most common public-API style because it's
   simple, universal, and built right on top of HTTP.

Interview Questions — Quick Fire!

Q: What is a REST API?

"REST is an architectural style for web APIs where everything is modeled as a resource — a noun — identified by a URL, and you act on it using standard HTTP methods: GET to read, POST to create, PUT to update, DELETE to remove. This makes APIs predictable and easy to use. It's built directly on HTTP and typically exchanges JSON."

Q: What are the key principles of REST?

"Client-server separation so they evolve independently; statelessness, where each request contains everything needed and the server keeps no client session; a uniform interface with consistent resource URLs and verbs; cacheability so responses can be cached; and a layered system where the client doesn't know if it's talking to the server directly or through intermediaries like proxies and load balancers."

Q: What does it mean for a REST API to be stateless?

"It means the server doesn't store any client session state between requests — each request must carry all the information needed to process it, such as an authentication token. This makes the API scalable, because any server can handle any request without needing shared session memory, which is ideal for horizontal scaling behind a load balancer."

Q: How would you design RESTful endpoints for users and their orders?

"I'd use plural nouns for resources and HTTP methods for actions: GET /users to list, POST /users to create, GET /users/1 for a specific user, PUT /users/1 to update, DELETE /users/1 to remove. For nested resources, GET /users/1/orders lists that user's orders and POST /users/1/orders creates one. I'd avoid putting verbs like getUser or createOrder in the URL, since the method already expresses the action."

Q: What makes a good REST API design?

"Using proper HTTP status codes so clients know what happened, versioning the API so changes don't break existing clients, paginating large collections instead of returning everything, using consistent plural nouns for predictable endpoints, supporting filtering and sorting via query parameters, returning JSON with a consistent error format, and securing it with HTTPS, authentication, and rate limiting."

Key Points to Remember

ConceptKey Takeaway
RESTResources (nouns) + HTTP methods (verbs) → predictable APIs on top of HTTP.
URL = nounMethod expresses the action; don't put verbs in URLs.
StatelessNo server-side session; each request self-contained → scales horizontally.
PrinciplesClient-server · stateless · uniform interface · cacheable · layered.
Good practicesStatus codes, versioning, pagination, plural nouns, JSON, security.

What's Next?

REST is request/response — the client always asks first. But what about live updates the server pushes? Chapter 10 closes the series with WebSockets, plus a look at how HTTP/2 and HTTP/3 made the web faster.

Keep learning, keep connecting! See you in the next one!