HTTP Fundamentals

HTTP (Hypertext Transfer Protocol) is the foundation of data communication on the web. Every web request/response follows this protocol. Understanding it thoroughly makes you a better API designer, debugger, and system architect.

Request & Response Structure

# HTTP Request structure:
# METHOD path HTTP-version
# Headers
# (blank line)
# Body

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
Accept: application/json
Content-Length: 52

{"name": "Jane Doe", "email": "jane@example.com"}

# HTTP Response structure:
# HTTP-version STATUS-CODE Reason-phrase
# Headers
# (blank line)
# Body

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/42
Cache-Control: no-cache
X-Request-Id: 7f3a9b2c

{"id": 42, "name": "Jane Doe", "createdAt": "2025-03-15T10:00:00Z"}

# Inspect with curl
curl -v https://api.example.com/users/1      # Show headers
curl -I https://example.com                  # HEAD request (headers only)
curl -s -o /dev/null -w "%{http_code}" https://example.com  # Status code only

HTTP Methods

# GET - retrieve a resource (safe, idempotent, cacheable)
curl https://api.example.com/users/42

# POST - create a resource or submit data (not idempotent, not safe)
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane","email":"jane@example.com"}'

# PUT - replace entire resource (idempotent)
curl -X PUT https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{"id":42,"name":"Jane Smith","email":"jane@example.com"}'

# PATCH - partial update (usually idempotent in practice)
curl -X PATCH https://api.example.com/users/42 \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Smith"}'

# DELETE - remove a resource (idempotent)
curl -X DELETE https://api.example.com/users/42

# HEAD - same as GET but no response body (check existence, headers)
curl -I https://api.example.com/users/42

# OPTIONS - discover allowed methods + CORS preflight
curl -X OPTIONS https://api.example.com/users \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: DELETE"

# CONNECT - establish tunnel (used for HTTPS through HTTP proxies)
# TRACE - diagnostic loopback (disabled on most servers)

# Method properties:
# Safe = does not modify server state (GET, HEAD, OPTIONS)
# Idempotent = repeated identical requests = same result (GET, PUT, DELETE, HEAD, OPTIONS)
# Cacheable = response can be cached (GET, HEAD, POST with explicit headers)

Status Codes

# 1xx Informational
100 Continue          # Client should proceed with request
101 Switching Protocols  # WebSocket upgrade

# 2xx Success
200 OK                # Standard success
201 Created           # Resource created (POST/PUT); include Location header
202 Accepted          # Request accepted for async processing
204 No Content        # Success with no response body (DELETE, PUT)
206 Partial Content   # Range request (video streaming, resume download)

# 3xx Redirection
301 Moved Permanently  # URL changed forever; browser caches it
302 Found              # Temporary redirect; method may change to GET
303 See Other          # Redirect to GET resource after POST (PRG pattern)
304 Not Modified       # Cached version is still valid (conditional GET)
307 Temporary Redirect # Temporary; method MUST NOT change
308 Permanent Redirect # Permanent; method MUST NOT change

# 4xx Client Errors
400 Bad Request        # Malformed syntax, invalid params
401 Unauthorized       # Authentication required (not yet authenticated)
403 Forbidden          # Authenticated but not authorized
404 Not Found          # Resource does not exist
405 Method Not Allowed # Method not supported for this resource
409 Conflict           # State conflict (duplicate, version mismatch)
410 Gone               # Resource permanently deleted
422 Unprocessable Entity  # Validation errors (REST APIs)
429 Too Many Requests  # Rate limit exceeded; add Retry-After header

# 5xx Server Errors
500 Internal Server Error  # Generic server fault
502 Bad Gateway            # Upstream server bad response
503 Service Unavailable    # Down for maintenance or overloaded
504 Gateway Timeout        # Upstream server timed out

HTTP/1.1 vs HTTP/2 vs HTTP/3

# Check which version a server uses
curl -sI --http2 https://example.com | head -1   # HTTP/2 200
curl -sI --http3 https://example.com | head -1   # HTTP/3 200

# HTTP/1.1 (1997, still widely used)
# - Text-based protocol
# - One request at a time per connection (head-of-line blocking)
# - Workaround: browsers open 6 parallel connections per origin
# - Keep-Alive for connection reuse
# - No header compression

# HTTP/2 (2015, ~65% of web traffic)
# - Binary framing layer (faster to parse)
# - Multiplexing: multiple requests over ONE connection simultaneously
# - Header compression (HPACK) - saves bandwidth
# - Server Push (push resources before client requests them)
# - Requires HTTPS in practice (browsers enforce it)
# - Still has TCP-level head-of-line blocking

# HTTP/3 (2022, ~30% and growing)
# - Based on QUIC protocol (UDP-based, not TCP)
# - Eliminates TCP head-of-line blocking
# - 0-RTT connection establishment (faster on reconnect)
# - Better on mobile/lossy networks
# - Built-in encryption (TLS 1.3 mandatory)
# - Connection migration (survive IP address changes)

# Verify with:
npx is-website-vulnerable https://example.com   # Security check
curl -w "%{http_version}" -o /dev/null -s https://example.com  # Print version