HTTP Methods, Status Codes, & Headers
Master the RESTful grammar of the web: Idempotency semantics, safe vs unsafe methods, status classes (2xx, 3xx, 4xx, 5xx), and caching/security headers.
HTTP Methods, Retries & Status Codes Lab
The first response is lost in the network — replay the request and watch which methods duplicate side effects.
POST: Unsafe and non-idempotent: N executions create N resources unless deduplicated. Not safe. Not idempotent.
201 Created with Location: /orders/{id} is the correct POST success code.
A real client hitting these failures would also honour Retry-After on 429/503 before backing off.
HTTP Method Semantics & Status Code Decision Tree 📊
Visual map of HTTP response codes and method idempotency rules.
01.Safe vs Idempotent Methods
- Safe Methods: Do not modify server state (
GET,HEAD,OPTIONS). They can be called freely — caches, intermediaries, and browsers can call them without side effects. - Idempotent Methods: Making
Nidentical requests has the exact same side-effect on server state as making 1 request (GET,PUT,DELETE). If a PUT to/users/42sets name to "Alice", calling it 10 times still results in name="Alice". - Non-Idempotent Methods: Making
Nrequests can createNduplicate resources (POST). POSTing to/orderstwice creates 2 orders.
Why it matters in Distributed Systems: If a network timeout occurs after sending a PUT or DELETE, the client can safely retry without fear of creating duplicate records. For POST, you must use an Idempotency-Key header to let the server detect and deduplicate retries.
02.Complete HTTP Status Code Reference
Understanding status codes is critical for building robust distributed systems — load balancers, circuit breakers, and monitoring dashboards all use them for health decisions.
03.Critical HTTP Headers in Distributed Systems
Headers carry metadata vital for caching, security, and tracing:
04.Caching Headers Deep Dive
HTTP caching is one of the most powerful performance optimizations available — a correctly cached response eliminates ALL server, database, and network cost for that request.
The Cache-Control header is composed of directives:
public: Can be stored by CDNs (shared caches)private: Only stored in browser (not CDNs) — use for personalized responsesmax-age=N: Browser cache lifetime in secondss-maxage=N: CDN cache lifetime (overrides max-age for shared caches)no-cache: Must revalidate with server before using cached copy (ETag check)no-store: Never cache, never store on disk (HIPAA/PCI data)immutable: Content will never change for this URL — skip revalidation (used with content-hashed asset filenames)
# Static assets (JS/CSS with content hash in filename)
Cache-Control: public, max-age=31536000, immutable
# API responses (personalized user data)
Cache-Control: private, max-age=60, must-revalidate
# CDN-cached API responses (shared, non-personalized)
Cache-Control: public, s-maxage=3600, max-age=60
# Sensitive financial/auth data — NEVER cache
Cache-Control: no-store, no-cache, must-revalidateArchitectural Trade-offs & Production Realities
Architectural Advantages
- Standardized status codes enable automated load balancer health checks and CDN caching logic
- Idempotency keys prevent duplicate charges and double-writes
Trade-offs & Constraints
- Misusing status codes (e.g. returning HTTP 200 with `{ error: "failed" }`) breaks monitoring dashboards
- Over-caching personalized data leaks user data across sessions
GitHub API uses `ETag` headers for 304 cache validation (saving client rate limits) and returns `X-RateLimit-Remaining` and `Retry-After` headers on 429 status codes.
Staff+ Engineering Takeaways
- Idempotent methods (GET, PUT, DELETE) can be safely retried upon network timeout.
- Use 429 for rate limiting, 502 for upstream crash, 503 for service overload.
- Use Idempotency-Key headers on POST operations to prevent duplicate payment charges.
- 401 = unauthenticated (missing/invalid token); 403 = unauthorized (valid token, wrong permissions).
- Cache-Control headers drive CDN behavior — `s-maxage` overrides `max-age` for shared caches.
Topic Knowledge Check
Exercise 1 of 1 • Test your architectural comprehension.
If a client sends an HTTP DELETE request to /users/42 and receives 200 OK, what should happen if the client sends the exact same DELETE request again?
How clear and actionable was this distributed systems breakdown?