6 REST Principles:

1. Client-Server    → Frontend and backend are separate
2. Stateless        → Each request contains all info needed
                       (no server-side session)
3. Cacheable        → Responses can be cached for performance
4. Uniform Interface → Consistent URL patterns and methods
5. Layered System   → Client doesn't know if it's talking to
                       the server directly or a load balancer
6. Code on Demand   → (Optional) Server can send executable
                       code to client (e.g., JavaScript)

Resource-based URLs (the RIGHT way):

✅ Good (nouns, resource-based):
  GET    /users/123
  POST   /users
  GET    /users/123/orders
  DELETE /users/123/orders/456

❌ Bad (verbs, action-based):
  GET    /getUser?id=123
  POST   /createUser
  GET    /getUserOrders?userId=123
  POST   /deleteOrder?id=456

Key rule: URLs identify RESOURCES (nouns).
HTTP methods define ACTIONS (verbs).

REST vs SOAP Comparison:

Feature        │ REST              │ SOAP
───────────────┼───────────────────┼──────────────────
Protocol       │ HTTP only         │ HTTP, SMTP, TCP
Data Format    │ JSON (mostly)     │ XML only
Weight         │ Lightweight       │ Heavyweight
Contract       │ No strict contract│ WSDL (strict)
Security       │ HTTPS, JWT, OAuth │ WS-Security
State          │ Stateless         │ Can be stateful
Caching        │ Built-in (HTTP)   │ No native caching
Error Handling │ HTTP status codes │ SOAP fault element
Learning Curve │ Easy              │ Complex

When to use REST:
- Web/mobile apps, microservices, public APIs
- When you need speed and simplicity

When to use SOAP:
- Banking/financial transactions (WS-Security)
- Enterprise integrations (SAP, Oracle)
- When you need strict contracts (WSDL)

In India: 90%+ new APIs are REST.
SOAP still found in BFSI and government systems.

HTTP Methods and CRUD Mapping:

Method  │ Action          │ Idempotent │ Safe
────────┼─────────────────┼────────────┼──────
GET     │ Read/Retrieve   │ Yes        │ Yes
POST    │ Create          │ No         │ No
PUT     │ Replace (full)  │ Yes        │ No
PATCH   │ Update (partial)│ Not always │ No
DELETE  │ Remove          │ Yes        │ No

CRUD Mapping:
  Create → POST   /users         (create new user)
  Read   → GET    /users/123     (get user by ID)
  Update → PUT    /users/123     (replace entire user)
         → PATCH  /users/123     (update specific fields)
  Delete → DELETE /users/123     (remove user)

Idempotency explained:
- Idempotent = same request multiple times = same result
- GET /users/123 → always returns same user
- DELETE /users/123 → first call deletes, next calls
  return 404 (but server state is the same)
- POST /users → each call creates a NEW user
  (NOT idempotent — this is why POST is different)

Interview tip: Always mention idempotency when
discussing HTTP methods. It shows depth.

HTTP Status Code Categories:

1xx → Informational (request received, processing)
2xx → Success (request accepted and processed)
3xx → Redirection (further action needed)
4xx → Client Error (bad request from client)
5xx → Server Error (server failed to process)

Must-Know Status Codes:

Success (2xx):
  200 OK              → Request succeeded
  201 Created         → Resource created (POST)
  204 No Content      → Success, no body (DELETE)

Redirection (3xx):
  301 Moved Permanently → URL changed permanently

Client Error (4xx):
  400 Bad Request     → Invalid request data
  401 Unauthorized    → Not authenticated (login first)
  403 Forbidden       → Authenticated but not authorized
  404 Not Found       → Resource doesn't exist
  405 Method Not Allowed → Wrong HTTP method
  409 Conflict        → Resource conflict (duplicate)
  422 Unprocessable   → Valid syntax, invalid data
  429 Too Many Requests → Rate limit exceeded

Server Error (5xx):
  500 Internal Server Error → Generic server failure
  502 Bad Gateway     → Upstream server failed
  503 Service Unavailable → Server overloaded/maintenance

Interview trap: 401 vs 403
  401 = "Who are you?" (not logged in)
  403 = "I know who you are, but no." (no permission)

PUT vs PATCH — Example:

Current user in database:
{
  "id": 123,
  "name": "Rahul",
  "email": "rahul@example.com",
  "age": 25
}

Goal: Update ONLY the email to "rahul@new.com"

PUT /users/123 (must send ALL fields):
{
  "name": "Rahul",
  "email": "rahul@new.com",
  "age": 25
}
// If you forget "age", it gets set to null!

PATCH /users/123 (send ONLY changed fields):
{
  "email": "rahul@new.com"
}
// Only email changes. name and age stay the same.

Key differences:
  PUT   → Replaces entire resource
  PATCH → Modifies specific fields

  PUT   → Must send complete object
  PATCH → Send only what changed

  PUT   → Always idempotent
  PATCH → May or may not be idempotent

When to use:
  PUT   → When client has the full updated object
  PATCH → When updating 1-2 fields (most common)

In practice: PATCH is used more often because
most updates are partial (change email, update status).

Authentication vs Authorization:

Authentication (AuthN):
  "Who are you?"
  → Login with username/password
  → Verify identity
  → Returns: token/session
  → Fails: 401 Unauthorized

Authorization (AuthZ):
  "What can you do?"
  → Check permissions/roles
  → Verify access rights
  → Returns: allowed/denied
  → Fails: 403 Forbidden

Real-world example:
  1. You log in to Instagram → Authentication
  2. You try to delete someone else's post → Authorization
     (you're authenticated but NOT authorized)

Flow in an API:
  Request → Authentication → Authorization → Resource
            (who are you?)   (can you do this?)

  POST /login
    → Verify credentials → Return JWT token
  
  DELETE /posts/456
    → Check JWT (authenticated?) → 401 if no
    → Check if user owns post (authorized?) → 403 if no
    → Delete post → 200 OK

Interview tip: Always connect 401 to authentication
and 403 to authorization. This shows clarity.

JWT Structure (3 parts separated by dots):

Header.Payload.Signature

1. Header (algorithm + type):
{
  "alg": "HS256",
  "typ": "JWT"
}

2. Payload (claims/data):
{
  "sub": "user123",
  "name": "Rahul",
  "role": "admin",
  "iat": 1516239022,
  "exp": 1516242622
}

3. Signature:
HMACSHA256(
  base64(header) + "." + base64(payload),
  secret_key
)

JWT Authentication Flow:

Client                          Server
  │                               │
  │  POST /login                  │
  │  {email, password}  ────────► │
  │                               │ Verify credentials
  │  ◄──────────  {token: "eyJ.."} │ Create JWT
  │                               │
  │  GET /profile                 │
  │  Authorization: Bearer eyJ..  │
  │  ────────────────────────────►│
  │                               │ Verify signature
  │  ◄──────────  {user data}     │ Extract payload
  │                               │

Key points:
- Stateless: no server-side session storage
- Self-contained: payload has all user info
- Stored: localStorage or httpOnly cookie
- Sent: Authorization: Bearer <token> header
- Expiry: tokens should expire (15min-24hr)

JWT vs OAuth 2.0 vs API Keys:

Feature    │ JWT           │ OAuth 2.0       │ API Key
───────────┼───────────────┼─────────────────┼──────────
What       │ Token format  │ Auth framework  │ Simple key
Purpose    │ User auth     │ Third-party     │ Server-to-
           │               │ access          │ server
Format     │ Header.Pay.Sig│ Access token +  │ String key
           │               │ refresh token   │
Stateless  │ Yes           │ Depends         │ Yes
Example    │ Login to app  │ "Login with     │ Google Maps
           │               │  Google"        │ API key

When to use each:

JWT:
  → User authentication in YOUR app
  → Stateless session management
  → Example: user logs in, gets JWT, sends with requests

OAuth 2.0:
  → Third-party access (Google/GitHub login)
  → "Allow App X to access your Google Drive"
  → Example: "Sign in with Google" button
  → Uses JWT internally for access tokens

API Key:
  → Server-to-server communication
  → Rate limiting and usage tracking
  → Example: calling Google Maps API
  → Sent as: ?api_key=abc123 or X-API-Key header

In practice, they work TOGETHER:
  OAuth 2.0 (framework) issues JWT (token format)
  API Keys protect public APIs from abuse

REST API Design Best Practices:

1. Naming Conventions:
   ✅ Nouns, not verbs: /users (not /getUsers)
   ✅ Plural resources: /users (not /user)
   ✅ Nested for relationships:
      /users/123/orders
      /users/123/orders/456
   ✅ Lowercase, hyphens: /user-profiles
   ❌ Avoid: /getUserById, /create_user

2. Versioning:
   /api/v1/users
   /api/v2/users
   → URL path versioning is most common in India

3. Pagination:
   GET /users?page=1&limit=20
   Response:
   {
     "data": [...],
     "pagination": {
       "page": 1,
       "limit": 20,
       "total": 150,
       "totalPages": 8
     }
   }

4. Filtering & Sorting:
   GET /users?status=active&sort=created_at&order=desc
   GET /products?category=electronics&min_price=1000

5. Error Response Format:
   {
     "error": {
       "code": "VALIDATION_ERROR",
       "message": "Email is required",
       "details": [
         { "field": "email", "message": "cannot be empty" }
       ]
     }
   }

6. HATEOAS (Hypermedia):
   {
     "id": 123,
     "name": "Rahul",
     "links": {
       "self": "/users/123",
       "orders": "/users/123/orders"
     }
   }

Rate Limiting:

Algorithms:
  1. Token Bucket → tokens refill at fixed rate
  2. Sliding Window → count requests in time window
  3. Fixed Window → count per time period

Response Headers:
  X-RateLimit-Limit: 100      (max requests)
  X-RateLimit-Remaining: 45   (requests left)
  X-RateLimit-Reset: 1623456  (reset timestamp)

When limit exceeded → 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Try after 60s",
    "retryAfter": 60
  }
}

Tiers: Free (100/hr), Pro (1000/hr), Enterprise (unlimited)

───────────────────────────────────────────

API Versioning Strategies:

1. URL Path (most common in India):
   /api/v1/users
   /api/v2/users

2. Header:
   Accept: application/vnd.myapi.v1+json
   Accept: application/vnd.myapi.v2+json

3. Query Parameter:
   /api/users?version=1
   /api/users?version=2

Breaking vs Non-Breaking Changes:
  Breaking (needs new version):
    → Removing a field
    → Changing field type
    → Changing URL structure

  Non-Breaking (safe to add):
    → Adding new optional field
    → Adding new endpoint
    → Adding new query parameter

Best practice: Support at least 2 versions.
Deprecate old versions with sunset headers.