RESTful API Design

Concept

REST (Representational State Transfer) is not a strict protocol; it is an architectural style for designing network applications. It uses standard HTTP methods (GET, POST, PUT, DELETE) to manipulate “Resources” (like Users, Orders, or Products) using stateless, cacheable URLs.

Mental Model

Think of an API as a library.

• Resource: The Book (/books/123).
• GET: “Let me read this book.”
• POST: “I wrote a new book, please add it to the library.” (/books)
• PUT/PATCH: “I need to fix a typo on page 5 of this book.”
• DELETE: “Throw this book in the trash.”

The Core Principles of REST

1. Client-Server Decoupling

The UI (React) and the Backend (Node.js) are completely independent. They only communicate via JSON over HTTP. You can rewrite the entire backend in Python and the React app will never know, as long as the JSON contract remains the same.

2. Statelessness

The server does not remember you between requests. Every single HTTP request must contain all the information necessary to authenticate and process it (e.g., passing a JWT token in the Authorization header). The server does not keep a “Session” variable in RAM. This allows you to scale to 100 API servers seamlessly, because any server can handle any request.

3. Resource-Based URLs (Nouns, not Verbs)

URLs should describe what the thing is, not what action you are doing to it.

• Bad: POST /createNewUser
• Bad: GET /getUsersList
• Good: POST /users
• Good: GET /users
• Good: GET /users/123/orders (Nested resources: Fetch orders belonging to user 123).

Status Codes (The Vocabulary)

You must use the correct HTTP Status Codes to tell the client what happened without them having to read the JSON.

• 200 OK: Success for GET/PUT/PATCH.
• 201 Created: Success for POST.
• 400 Bad Request: The user messed up (e.g., missing required email field).
• 401 Unauthorized: The user didn’t provide a valid token.
• 403 Forbidden: The user has a valid token, but isn’t an Admin.
• 404 Not Found: The resource doesn’t exist.
• 500 Internal Server Error: The backend code crashed.

Real-World Usage

• Stripe API: Often considered the gold standard of RESTful API design.
• Pagination: REST APIs returning lists should never return 10,000 items at once. They must use pagination (GET /users?limit=20&page=2 or cursor-based pagination).
• Versioning: Always version your APIs from Day 1 (/v1/users). If you make a breaking change later, you create /v2/users so older mobile apps don’t instantly crash.

Interview Questions

Q: Explain the difference between PUT and PATCH.
A: Both are used to update a resource, but they have different rules:

• PUT is Idempotent and Replaces: It replaces the entire resource. If a User has name and age, and you PUT {"name": "Alice"}, the server must delete the age field because you didn’t provide it.
• PATCH is a Partial Update: It only modifies the fields you provide. PATCH {"name": "Alice"} will change the name but leave the existing age intact in the database.

Q: Why is it bad practice to store user session data in server RAM when building a REST API?
A: This violates the Statelessness principle of REST. If Server A stores “User is logged in” in its RAM, and the Load Balancer routes the user’s next request to Server B, Server B will reject the request because it doesn’t have the session data. You would be forced to use “Sticky Sessions” on the Load Balancer (forcing a user to always hit Server A), which destroys your ability to scale and distribute traffic evenly.