HTTP/1.1, HTTP/2, REST API Architecture & OpenAPI

Building web services in Python requires a thorough understanding of the underlying network protocols: HTTP/1.1, HTTP/2 (multiplexed streams over TCP), and HTTP/3 (QUIC over UDP). Designing robust backend interfaces requires adhering to RESTful API Principles, method idempotency rules, content negotiation headers, and OpenAPI (Swagger) specifications.

This chapter details HTTP protocol evolution, RESTful constraints, HTTP method Safety vs Idempotency, and OpenAPI schema generation.

---

1. Protocol Evolution: HTTP/1.1 vs. HTTP/2 vs. HTTP/3

HTTP Protocol Evolution Comparison:

1. HTTP/1.1 (TCP):
   - Head-of-Line (HOL) Blocking: Each TCP connection handles 1 request/response at a time.
   - Verbose plain-text headers.

2. HTTP/2 (TCP + TLS):
   - Binary Framing Layer: Multiplexes hundreds of requests concurrently over a SINGLE TCP connection!
   - HPACK Header Compression & Server Push.
   - Weakness: TCP packet loss stalls ALL multiplexed streams (TCP-level HOL blocking).

3. HTTP/3 (UDP + QUIC):
   - Built on QUIC (UDP protocol with embedded TLS 1.3 encryption).
   - Zero TCP Head-of-Line blocking! Independent streams ensure packet loss affects ONLY that specific stream!

---

2. RESTful API Architecture & Method Semantics

Representational State Transfer (REST) is an architectural style based on 6 core constraints: Statelessness, Client-Server separation, Cacheability, Uniform Interface, Layered System, and Code on Demand.

HTTP Method Matrix (Safety vs. Idempotency):

Safety: An HTTP method is Safe if it does NOT modify resource state on the server (Read-Only).
Idempotency: An HTTP method is Idempotent if executing it $N$ times produces the exact same server state as executing it once.

Method	Safe?	Idempotent?	Description	Primary Status Code
GET	✅ Yes	✅ Yes	Retrieves resource representation	200 OK
HEAD	✅ Yes	✅ Yes	Retrieves headers only (no body payload)	200 OK
POST	❌ No	❌ No	Creates a new resource or triggers processing	201 Created
PUT	❌ No	✅ Yes	Replaces resource entirely (or creates at exact URI)	200 OK / 204 No Content
PATCH	❌ No	❌ No	Partially mutates specific resource fields	200 OK
DELETE	❌ No	✅ Yes	Removes target resource	204 No Content

---

3. Content Negotiation & HTTP Status Codes

Clients specify desired payload representations using Accept headers, while servers report capabilities using Content-Type:

• Accept: application/json $\rightarrow$ Server responds with Content-Type: application/json.
• 406 Not Acceptable: Returned if server cannot fulfill the requested Accept format.

Key HTTP Status Code Families:

• 2xx (Success): 200 OK, 201 Created, 204 No Content.
• 3xx (Redirection): 301 Moved Permanently, 304 Not Modified (HTTP Caching).
• 4xx (Client Error): 400 Bad Request, 401 Unauthorized (Un-authenticated), 403 Forbidden (Authenticated but lacking permissions), 404 Not Found, 409 Conflict, 422 Unprocessable Entity (Pydantic validation failure).
• 5xx (Server Error): 500 Internal Server Error, 502 Bad Gateway (Nginx/Reverse Proxy failed to contact Gunicorn), 503 Service Unavailable, 504 Gateway Timeout.

---

4. OpenAPI Specifications (Swagger)

OpenAPI provides a machine-readable JSON/YAML contract defining paths, parameters, request bodies, and authentication schemes. Python web frameworks (FastAPI) auto-generate OpenAPI schemas directly from function type hints and Pydantic models.

# ❌ ANTI-PATTERN: Non-Idempotent PUT & Misused 401 Status Code
@app.put("/account/balance")
def add_balance(amount: float):
    # BAD: Mutating balance additively inside PUT is NOT Idempotent! Retries double-charge!
    account.balance += amount
    return account

# ✅ PRODUCTION PATTERN: Idempotent PUT & Proper REST Semantics
@app.put("/account/balance")
def set_balance(payload: BalanceUpdateSchema):
    # SAFE: Setting absolute balance is Idempotent! 10 retries produce identical state!
    account.balance = payload.target_balance
    return account