Software engineering fundamental: Separating concerns through interfaces

Within a single application:

# User management module
def create_user(email, password):
    user_id = generate_id()
    hash_pwd = hash_password(password)
    store_user(user_id, email, hash_pwd)
    return user_id

# Booking module
def create_booking(user_id, flight_id):
    user = get_user(user_id)  # Function call
    if user.is_active:
        return store_booking(user_id, flight_id)

Module boundaries provide:

• Separation of concerns: User logic isolated from booking logic
• Independent modification: Change password hashing without touching bookings
• Contract-based interface: get_user(user_id) → User defines expectations
• Parallel development: Different developers work on different modules

Single process limitation:

• Shared memory space: Module bug can crash entire application
• Shared resources: CPU-intensive user validation blocks booking requests
• Deployment coupling: Update user module requires redeploying bookings
• Technology lock-in: All modules must use same language/framework

Moving from modules to separate processes

Same code, different execution model:

# User service (separate process)
# Listens on port 8001
@app.route('/users', methods=['POST'])
def create_user():
    email = request.json['email']
    password = request.json['password']
    user_id = generate_id()
    hash_pwd = hash_password(password)
    store_user(user_id, email, hash_pwd)
    return {'user_id': user_id}

# Booking service (separate process)
# Listens on port 8002
@app.route('/bookings', methods=['POST'])
def create_booking():
    user_id = request.json['user_id']
    flight_id = request.json['flight_id']

    # HTTP request instead of function call
    response = requests.get(f'http://localhost:8001/users/{user_id}')
    user = response.json()

    if user['is_active']:
        return store_booking(user_id, flight_id)

Why separate processes:

• Failure isolation: User service crash doesn’t terminate booking service
• Resource isolation: CPU-intensive user validation doesn’t block booking requests
• Independent deployment: Update user service without restarting booking service
• Technology flexibility: User service in Python, booking service in Go

API: Application Programming Interface - contract for communication

Function call contract:

def get_user(user_id: int) -> User:
    """
    Contract:
    - Input: user_id (integer)
    - Output: User object with fields: id, email, is_active
    - Raises: UserNotFoundError if user_id doesn't exist
    """
    pass

HTTP API contract for same operation:

Request: GET /users/123 on host user-service:8001

Success response: HTTP 200 OK

{
  "user_id": 123,
  "email": "alice@example.com",
  "is_active": true
}

Not found response: HTTP 404 Not Found

{
  "error": "User not found",
  "user_id": 123
}

API contract specifies:

• Endpoint: GET /users/123 identifies resource and operation
• Input format: User ID in URL path
• Success response: JSON with user_id, email, is_active fields (status 200)
• Error response: JSON with error message (status 404)

Why explicit contracts matter:

Services can evolve independently:

• Booking service knows the user API returns is_active field
• User service can change implementation (database, caching) without breaking bookings
• Contract violations detected immediately: 404 instead of silent failure

API documentation as contract:

GET /users/:user_id — Retrieve user by ID

Parameters:

• user_id (integer, path, required): User identifier

Responses:

• 200 User found: Returns user_id (integer), email (string), is_active (boolean)
• 404 Not found: Returns error (string), user_id (integer)
• 500 Server error: Internal error occurred

Contract enforcement:

• Booking service expects specific JSON structure
• User service must provide that structure
• Change requires coordination: Update contract, then implementation
• Compare to function call: Type system enforces contract at compile time

APIs make implicit function contracts explicit and enforceable

Scenario: User service needs to add email verification

Version 1 response: GET /users/123

{
  "user_id": 123,
  "email": "alice@example.com",
  "is_active": true
}

Version 2 - Adding fields (backward compatible)

{
  "user_id": 123,
  "email": "alice@example.com",
  "is_active": true,
  "email_verified": true,           // New field
  "verification_date": "2025-01-15" // New field
}

Backward compatible change:

• Booking service ignores unknown fields
• Continues using is_active as before
• No coordination required

Version 2 - Breaking change (not compatible)

{
  "user_id": 123,
  "email": "alice@example.com",
  "account_status": "active_verified"  // Replaced is_active
}

Problem: Booking service still reads is_active field

• Field doesn’t exist in response
• Booking service interprets as false or crashes
• Breaking change requires coordinated deployment

Version management strategies:

URL-based versioning:

• GET /v1/users/123 → Old response (includes is_active)

• GET /v2/users/123 → New response (includes account_status)

• Booking service continues using /v1/users

• New services can use /v2/users

• User service maintains both versions temporarily

Version distribution (airline system, 45 days after v2 launch):

• v1 endpoint: 12% of requests (older services)
• v2 endpoint: 88% of requests (updated services)

Cannot remove v1 until 100% migrated

Why versioning needed:

• 20 services depend on user API
• Coordinated update across 20 services: weeks of planning
• Independent updates with versioning: gradual rollout
• Compare to function signature change: Compiler forces simultaneous update

APIs enable independent deployment through versioning

API serves multiple independent consumers

Four clients calling GET /users/123:

1. Booking service — Checks is_active before creating booking
2. Email service — Sends email to user['email']
3. Admin dashboard — Displays user profile
4. Mobile app — Renders profile screen (external client via https://api.airline.com)

All four clients depend on same contract

Client code example:

response = requests.get('http://user-service:8001/users/123')
user = response.json()
if user['is_active']:
    create_booking(...)

Internal change in user service:

# Original: Users stored in PostgreSQL
def get_user(user_id):
    row = db.query("SELECT * FROM users WHERE id = ?", user_id)
    return {
        'user_id': row['id'],
        'email': row['email'],
        'is_active': row['active']
    }

# New: Users moved to Redis cache (performance improvement)
def get_user(user_id):
    cached = redis.get(f'user:{user_id}')
    if cached:
        return json.loads(cached)
    # Fallback to database...

Impact on clients: None

• API contract unchanged: Still returns same JSON structure
• Implementation details hidden behind API
• Database → Redis migration invisible to consumers
• No client code changes required

Contract violation example:

User service developer changes field name:

# Accidentally changed field name
return {
    'user_id': row['id'],
    'email_address': row['email'],  # Was 'email'
    'is_active': row['active']
}

Cascading failures:

• Booking service: KeyError: 'email' when sending confirmation
• Email service: Crashes attempting to read user email
• Admin dashboard: Profile page displays blank email
• Mobile app: 500 errors rendered to users

4 clients break simultaneously from single field rename

Why contracts matter with multiple clients:

• Function rename in module: Compiler catches all call sites
• API field rename: No compile-time check, runtime failures
• More clients = higher cost of breaking changes
• Explicit contract + automated testing prevents accidental breakage

APIs require stability when serving multiple independent clients

HTTP request anatomy:

GET /users/123 HTTP/1.1
Host: user-service.airline.com
Authorization: Bearer eyJhbGc...
Accept: application/json
User-Agent: booking-service/2.1.0

Request line components:

• Method: GET - what operation to perform
• Path: /users/123 - which resource to access
• Protocol: HTTP/1.1 - version of HTTP

Request headers (metadata):

• Host: Which server to route to (required in HTTP/1.1)
• Authorization: Credentials for authentication
• Accept: What response format client understands
• User-Agent: Identifies client making request

Headers are key-value pairs: Header-Name: value

Empty line separates headers from body

Requests without body (GET, DELETE) end after headers

Typical request size:

• Typical GET request: 250-400 bytes
• Headers: 200-350 bytes
• Request line: 50 bytes

HTTP response anatomy:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 145
Cache-Control: max-age=300
Date: Mon, 15 Jan 2025 14:30:00 GMT

{
  "user_id": 123,
  "email": "alice@example.com",
  "is_active": true,
  "created_at": "2024-01-10T08:00:00Z"
}

Status line components:

• Protocol: HTTP/1.1
• Status code: 200 - numeric result indicator
• Reason phrase: OK - human-readable description

Response headers:

• Content-Type: Format of response body (JSON, HTML, etc)
• Content-Length: Body size in bytes
• Cache-Control: How long response can be cached
• Date: When response was generated

Response body:

• Actual data returned by server
• Format specified by Content-Type header
• In this case: JSON with user data

Empty line separates headers from body (same as request)

Status code tells client what happened and what to do next

response = requests.get('http://user-service/users/123')

if response.status_code == 200:
    user = response.json()  # Success - process data
    
elif response.status_code == 404:
    return None  # User doesn't exist - normal case
    
elif response.status_code == 401:
    refresh_token()  # Get new auth token
    retry_request()   # Try again
    
elif response.status_code == 503:
    time.sleep(5)     # Service down
    retry_request()   # Retry with backoff
    
elif response.status_code >= 500:
    alert_ops_team()  # Server problem
    return fallback_response()

Different codes require different handling:

2xx: Process response
4xx: Fix request or handle business logic
5xx: Retry or use fallback

Common status codes in production:

200 OK — Request succeeded
Return data in response body

201 Created — Resource created
Location header has new resource URL

204 No Content — Success, no data
DELETE succeeded, nothing to return

400 Bad Request — Malformed request
Invalid JSON, missing required field

401 Unauthorized — No valid auth
Token expired or missing

403 Forbidden — Not allowed
Valid auth but wrong permissions

404 Not Found — Resource missing
Normal for checking existence

429 Too Many Requests — Rate limited
Check Retry-After header

500 Internal Server Error — Bug
Unhandled exception in server

503 Service Unavailable — Overloaded
Retry with exponential backoff

4xx = Your request has a problem

POST /users
Content-Type: application/json

{"email": "not-an-email", "age": "twenty"}

Response: 400 Bad Request

{
  "errors": [
    {"field": "email", "message": "Invalid email format"},
    {"field": "age", "message": "Must be integer"}
  ]
}

Client must fix the request:

• Validate input before sending
• Check required fields
• Use correct data types

5xx = Server has a problem

# Server code with bug
@app.route('/users/<id>')
def get_user(id):
    user = db.query(f"SELECT * FROM users WHERE id = {id}")
    return user.to_dict()  # Crashes if user is None

Response: 500 Internal Server Error

{
  "error": "Internal server error",
  "request_id": "7f3c6b2a"
}

Client should retry (server might recover):

• Use exponential backoff
• Have circuit breaker
• Log for debugging

Retry strategies differ:

4xx errors: Don’t retry same request

• Fix the problem first
• 401: Get new token
• 429: Wait for rate limit reset

5xx errors: Retry might work

• Server might recover
• Different server might work
• Use exponential backoff

429 Too Many Requests — You’re sending too fast

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1697299200
Retry-After: 60

{
  "error": "Rate limit exceeded",
  "limit": 100,
  "window": "per hour",
  "retry_after_seconds": 60
}

Client must slow down:

if response.status_code == 429:
    retry_after = response.headers.get('Retry-After', 60)
    time.sleep(int(retry_after))
    # Or queue request for later

503 Service Unavailable — Server overloaded

HTTP/1.1 503 Service Unavailable
Retry-After: 30

Server is temporarily unable to handle requests:

• Too many connections
• Database down
• Deployment in progress

Different causes, different handling:

429 = Rate limiting (intentional)

• Protects service from abuse
• Per-client limits
• Predictable reset times
• Client should queue/batch requests

503 = Overload (unintentional)

• Service can’t handle load
• Affects all clients
• Unknown recovery time
• Client should back off

Exponential backoff pattern:

def retry_with_backoff(func, max_retries=5):
    for attempt in range(max_retries):
        response = func()
        if response.status_code == 503:
            wait = 2 ** attempt  # 1, 2, 4, 8, 16
            time.sleep(wait)
        else:
            return response
    raise Exception("Max retries exceeded")

Circuit breaker pattern:

• After N failures, stop trying
• Let service recover
• Periodically test if service back

HTTP methods specify the operation type

GET — Read data

GET /users/123

Returns user 123’s data. No changes to server state.

POST — Create new

POST /users
{"email": "alice@example.com", "password": "..."}

Creates new user. Server assigns ID.

PUT — Replace entirely

PUT /users/123
{"email": "new@example.com", "is_active": false}

Replaces ALL fields of user 123.

PATCH — Update partially

PATCH /users/123
{"email": "new@example.com"}

Updates ONLY email, leaves other fields unchanged.

DELETE — Remove

DELETE /users/123

Removes user 123 from system.

Critical property: Idempotency

Idempotent = Same result from multiple identical calls

Why idempotency matters:

Network fails after server processes but before client gets response.

Idempotent (PUT, DELETE):

• Client can safely retry
• No duplicate side effects

Not idempotent (POST):

• Retry might create duplicate
• Need idempotency keys

Safe = No server state changes
Only GET is safe (can cache, prefetch)

POST - Server assigns identifier

# Client doesn't know ID yet
POST /users
{
  "email": "alice@example.com",
  "name": "Alice"
}

# Server response
201 Created
Location: /users/456
{
  "id": 456,  # Server assigned
  "email": "alice@example.com",
  "name": "Alice",
  "created_at": "2024-01-15T10:30:00Z"
}

PUT - Client specifies identifier

# Client knows ID (e.g., using email as ID)
PUT /users/alice@example.com
{
  "name": "Alice",
  "role": "admin"
}

# Server response
200 OK  # Or 201 if newly created
{
  "id": "alice@example.com",
  "name": "Alice",
  "role": "admin"
}

POST is not idempotent:

# Call POST twice with same data
POST /users {"email": "bob@example.com"}
POST /users {"email": "bob@example.com"}

# Result: Two users created (IDs 457, 458)
# Or: 409 Conflict on second request

When to use each:

Use POST when:

• Server generates IDs (auto-increment, UUID)
• Creating dependent resources
• Running actions/commands
• Resource location unknown

Use PUT when:

• Client controls IDs
• Replacing entire resource
• Upsert operations (create or update)
• Resource location known

Real examples:

GitHub:

POST /repos/owner/repo/issues
# Creates issue, GitHub assigns number

PUT /repos/owner/repo/contents/README.md
# Creates/replaces file at exact path

AWS S3:

PUT /bucket/object-key
# Always PUT - client controls key
# Creates new or replaces existing

Idempotency in practice:

• PUT same data multiple times = one resource
• POST same data multiple times = multiple resources (or error)

PUT replaces entire resource

# Current user state
{
  "id": 123,
  "email": "alice@example.com",
  "name": "Alice",
  "role": "user",
  "is_active": true
}

# PUT request (missing fields)
PUT /users/123
{
  "email": "alice@example.com",
  "name": "Alice Updated"
}

# Result - other fields lost/defaulted
{
  "id": 123,
  "email": "alice@example.com",
  "name": "Alice Updated",
  "role": null,      # Lost!
  "is_active": false  # Lost!
}

PATCH updates only specified fields

# PATCH request
PATCH /users/123
{
  "name": "Alice Updated"
}

# Result - other fields unchanged
{
  "id": 123,
  "email": "alice@example.com",  # Unchanged
  "name": "Alice Updated",        # Changed
  "role": "user",                 # Unchanged
  "is_active": true                # Unchanged
}

Common PATCH formats:

JSON Merge Patch (simple):

{
  "name": "New Name",
  "email": "new@example.com"
}

JSON Patch (RFC 6902):

[
  {"op": "replace", "path": "/name", "value": "New Name"},
  {"op": "add", "path": "/tags/0", "value": "premium"},
  {"op": "remove", "path": "/temp_field"}
]

When to use each:

PUT:

• Form submissions (have all fields)
• Config file updates
• Immutable updates

PATCH:

• Single field updates
• Large resources
• Partial forms
• Mobile apps (bandwidth)

Common mistake: Using PUT for single field update loses data

# WRONG: PUT with one field
PUT /users/123
{"email": "new@example.com"}
# Lost all other fields!

Safe methods can be called without side effects

# Safe to retry, cache, prefetch
GET /users/123
GET /users/123  # Same result
GET /users/123  # Same result

# Browser/proxy can cache
Cache-Control: max-age=300

Unsafe methods change server state

# DELETE is idempotent but unsafe
DELETE /users/123  # Returns 204 No Content
DELETE /users/123  # Returns 404 Not Found
DELETE /users/123  # Returns 404 Not Found
# Final state same, but state did change

# POST is neither safe nor idempotent  
POST /orders       # Creates order 1
POST /orders       # Creates order 2 (duplicate!)
POST /orders       # Creates order 3 (duplicate!)

Network failure handling:

try:
    response = requests.post('/orders', data)
except requests.Timeout:
    # Did server process request before timeout?
    # Can't know - need idempotency key

Retry safety:

Always safe: GET
Safe if idempotent: PUT, DELETE
Dangerous: POST, PATCH

Need idempotency keys for POST/PATCH

Creating new booking via POST:

POST /bookings HTTP/1.1
Host: booking-service.airline.com
Content-Type: application/json
Content-Length: 215
Authorization: Bearer eyJhbGc...

{
  "user_id": 123,
  "flight_id": 456,
  "seat": "12A",
  "payment": {
    "method": "credit_card",
    "amount": 450.00,
    "currency": "USD"
  },
  "notifications": {
    "email": true,
    "sms": false
  }
}

Additional headers for body:

• Content-Type: Specifies body format (JSON, XML, form data)
• Content-Length: Exact size in bytes (required by HTTP/1.1)

Server response:

HTTP/1.1 201 Created
Location: /bookings/789
Content-Type: application/json
Content-Length: 87

{
  "booking_id": 789,
  "status": "confirmed",
  "confirmation_code": "ABC123"
}

201 Created status indicates:

• New resource successfully created
• Location header provides URL to access new resource
• Response body contains resource details

HTTP runs over TCP connection:

1. TCP handshake (connection establishment):

Client            Server
  |                 |
  |--- SYN -------->| (50ms)
  |<-- SYN-ACK -----| (50ms)
  |--- ACK -------->| (50ms)
  |                 |
  [TCP established]

• 3-way handshake establishes connection
• Total latency: 150ms (client-server round trip)
• Required before any HTTP data sent

2. HTTP request/response over established connection:

  |                 |
  |- GET /users/123->| (50ms)
  |<- 200 OK + data -| (50ms)
  |                 |

• Request sent over TCP connection
• Response returned on same connection
• Total: 100ms for request/response

3. Connection close:

  |                   |
  |---- FIN --------->|
  |<--- FIN-ACK ------|
  |                   |
  [Connection closed]

Total measured latency for single request:

• TCP handshake: 150ms
• HTTP request/response: 100ms
• Total: 250ms

Round-trip latency varies by distance:

• Same datacenter: 1-2ms per round trip
• Cross-coast US: 60-80ms per round trip
• Transpacific: 150-200ms per round trip

3-way handshake before HTTP request

TCP connections are expensive to establish — each requires a 3-way handshake before any data transfers

Without keep-alive (HTTP/1.0 default):

Request 1:
  TCP handshake: 150ms
  HTTP request/response: 100ms
  Close connection
  Total: 250ms

Request 2:
  TCP handshake: 150ms (again!)
  HTTP request/response: 100ms
  Close connection
  Total: 250ms

Request 3:
  TCP handshake: 150ms (again!)
  HTTP request/response: 100ms
  Close connection
  Total: 250ms

Total for 3 requests: 750ms

With keep-alive (HTTP/1.1 default):

Request 1:
  TCP handshake: 150ms
  HTTP request/response: 100ms
  Keep connection open
  Total: 250ms

Request 2:
  HTTP request/response: 100ms
  (reuse connection)
  Total: 100ms

Request 3:
  HTTP request/response: 100ms
  (reuse connection)
  Total: 100ms

Total for 3 requests: 450ms

40% latency reduction by reusing connection

Keep-alive headers:

Request includes: Connection: keep-alive Response includes: Connection: keep-alive and Keep-Alive: timeout=5, max=1000

Keep-alive parameters:

• timeout=5: Server keeps connection open for 5 seconds idle
• max=1000: Maximum 1000 requests on this connection

Connection pooling in practice:

import requests

# Creates connection pool (default 10 connections)
session = requests.Session()

# All requests reuse connections from pool
for user_id in range(100):
    response = session.get(f'http://user-service:8001/users/{user_id}')
    # Connections automatically returned to pool

Estimated impact (100 sequential requests, cross-coast):

• Without keep-alive: 25 seconds (250ms × 100)
• With keep-alive (10 connections in pool): 3.5 seconds
• 7× improvement

Connection reuse critical for performance

A single connection serializes requests — concurrent clients need concurrent connections

Single connection serves requests sequentially:

Connection 1: [Req1]->[Resp1]->[Req2]->[Resp2]->[Req3]->[Resp3]

Connection pool serves requests in parallel:

Connection 1: [Req1]->[Resp1]        [Req4]->[Resp4]
Connection 2:        [Req2]->[Resp2]        [Req5]->[Resp5]  
Connection 3:               [Req3]->[Resp3]

Connection pool implementation:

from urllib3 import PoolManager

# Create pool with size limits
pool = PoolManager(
    num_pools=10,      # Max 10 different hosts
    maxsize=20,        # Max 20 connections per host
    block=True         # Wait if pool exhausted
)

# Connections managed automatically
response = pool.request('GET', 'http://api/users/123')
# Connection returned to pool after response read

Pool sizing considerations:

• Too small: Requests wait for available connection
• Too large: Memory overhead, server connection limits
• Typical: 10-50 connections per host

Pool exhaustion behavior:

# Pool size: 2, but 3 concurrent requests
pool = PoolManager(maxsize=2)

# Thread 1: Gets connection
# Thread 2: Gets connection  
# Thread 3: Blocks waiting for available connection
# Thread 1 completes: Connection returned to pool
# Thread 3: Gets recycled connection

Real scenarios requiring pools:

• Web server → Database (10-20 connections)
• API Gateway → Backend services (50-100 per service)
• Microservice → Other microservices (10-30 per service)

HTTP headers determine how services process requests

Four critical functions in distributed systems:

1. Authentication/Authorization Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Service validates identity and permissions before processing

2. Content Negotiation Content-Type: application/json; charset=utf-8 Accept: application/json

Ensures correct parsing and response format

3. Request Correlation X-Request-ID: 7f3c6b2a-5d9e-4f8b-a1c3-9e8d7c6b5a4f

Traces requests across multiple services for debugging

4. Service Metadata User-Agent: booking-service/2.1.0 X-API-Version: 2

Enables version-specific handling and deprecation

What happens without proper headers:

Missing Authorization → 401 Unauthorized
Wrong Content-Type → Data corruption
No X-Request-ID → Can’t trace failures
Invalid Accept → Client can’t parse response

Headers every request needs:

• Authorization — Identity and permissions
• Content-Type — How to parse body
• Accept — What format you want back

Headers for debugging:

• X-Request-ID — Correlation across services
• User-Agent — Which client sent this

Headers in responses:

• Status code — Did it work?
• X-RateLimit-Remaining — Quota status
• Cache-Control — Can this be cached?

Headers are contracts between services

Content-Type tells server how to parse request body

POST /models/123/predict
Content-Type: application/json; charset=utf-8
Accept: application/json

{"features": [1.2, 3.4, 5.6], "threshold": 0.8}

Server uses Content-Type to route parsing:

@app.route('/models/<id>/predict', methods=['POST'])
def predict(id):
    content_type = request.headers.get('Content-Type', '')
    
    if 'application/json' in content_type:
        data = request.get_json()  # JSON parser
    elif 'application/x-www-form-urlencoded' in content_type:
        data = request.form        # Form parser
    elif 'multipart/form-data' in content_type:
        data = request.files       # File parser
    else:
        return {'error': 'Unsupported Content-Type'}, 415
    
    # Check Accept header for response format
    accept = request.headers.get('Accept', 'application/json')
    if 'application/json' not in accept:
        return {'error': 'Cannot produce requested format'}, 406
    
    result = model.predict(data)
    return jsonify(result), 200

How wrong Content-Type corrupts data:

# Client sends JSON with wrong header
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
body = json.dumps({'key': 'value'})

# Server parses as form, gets garbage
request.form = {'{"key": "value"}': ''}

Content-Type controls parsing:

application/json → JSON parser
application/x-www-form-urlencoded → Form parser
multipart/form-data → File upload parser
application/octet-stream → Raw bytes

Why explicit headers matter:

• Wrong Content-Type silently corrupts data
• Missing Accept causes client parse failures
• No charset breaks Unicode characters

Every request should include:

headers = {
    'Content-Type': 'application/json; charset=utf-8',
    'Accept': 'application/json'
}

REST: Representational State Transfer

Architectural style, not a protocol or standard

Coined by Roy Fielding (2000 dissertation) based on HTTP design principles

Core idea: Resources identified by URLs, manipulated via standard HTTP methods

What REST is NOT:

• Not a specification with compliance tests
• Not a protocol like HTTP or SOAP
• Not limited to JSON (can use XML, HTML, etc)
• Not the only way to design APIs

What REST provides:

• Set of design principles for building APIs
• Conventions for mapping operations to HTTP methods
• Guidelines for URL structure
• Constraints that enable scalability and simplicity

REST vs other approaches:

• RPC-style: /createUser, /getUser, /deleteUser (verbs in URLs)
• REST-style: POST /users, GET /users/123, DELETE /users/123 (resources + methods)

REST treats everything as a resource accessible via URL

REST principle: URLs identify resources (things), methods specify operations

Resource hierarchy in airline API:

User resources:

• /users — Collection of all users
• /users/123 — Specific user
• /users/123/bookings — User’s bookings (sub-collection)
• /users/123/bookings/789 — Specific booking

Flight resources:

• /flights — Collection of all flights
• /flights/456 — Specific flight
• /flights/456/seats — Available seats

Airport resources:

• /airports — Collection of airports
• /airports/LAX — Specific airport
• /airports/LAX/flights — Flights from LAX

URL structure conventions:

• Use plural nouns: /users not /user
• Use hyphens for readability: /frequent-flyers not /frequentFlyers
• Nest resources to show relationships: /users/123/bookings
• Keep hierarchy shallow (2-3 levels maximum)

Operations via HTTP methods:

• GET /users — Get all users
• GET /users/123 — Get specific user
• POST /users — Create new user (body: email, password)
• PUT /users/123 — Update user (body: complete resource)
• DELETE /users/123 — Delete user

Nested resources show relationships:

GET /users/123/bookings returns array of user’s bookings:

[
  {"booking_id": 789, "flight_id": 456, "seat": "12A", ...},
  {"booking_id": 790, "flight_id": 457, "seat": "14B", ...}
]

GET /users/123/bookings/789 returns specific booking via user path:

{
  "booking_id": 789,
  "user_id": 123,
  "flight_id": 456,
  "seat": "12A",
  "status": "confirmed"
}

GET /bookings/789 returns same booking via direct path:

{
  "booking_id": 789,
  "user_id": 123,
  "flight_id": 456,
  "seat": "12A",
  "status": "confirmed"
}

Design choice: Provide both paths when resource makes sense independently

• /users/123/bookings — User-centric view (all bookings for user)
• /bookings/789 — Booking-centric view (single booking)

Different access patterns for different use cases

GET retrieves resource without modification

Request targets specific resource by ID:

GET /users/456 HTTP/1.1

Server returns resource representation:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "user_id": 456,
  "email": "carol@example.com",
  "name": "Carol Chen",
  "is_active": true,
  "created_at": "2025-01-15T14:30:00Z"
}

GET characteristics:

• No request body (parameters in URL or query string)
• 200 OK when resource exists
• 404 Not Found when resource doesn’t exist
• Idempotent: Repeated calls return same data
• Safe: No side effects on server state

GET on collections returns multiple resources:

GET /users HTTP/1.1

HTTP/1.1 200 OK

{
  "users": [
    {"user_id": 456, "email": "carol@example.com", ...},
    {"user_id": 457, "email": "bob@example.com", ...}
  ],
  "count": 2
}

DELETE removes resource

Request targets specific resource:

DELETE /users/456 HTTP/1.1

Server removes resource, returns minimal response:

HTTP/1.1 204 No Content

DELETE characteristics:

• No request body
• 204 No Content on success (nothing to return)
• 404 Not Found if resource already deleted
• Idempotent: Multiple deletes produce same final state

Subsequent DELETE returns 404:

First delete:

DELETE /users/456 → 204 No Content (deleted)

Second delete:

DELETE /users/456 → 404 Not Found (already gone)

Final state identical: User 456 doesn’t exist

Both methods are idempotent:

• GET: Same data returned each time
• DELETE: Same final state (resource absent)

Idempotency enables safe retries on network failures

POST creates new resource

Request sent to collection URL:

POST /users HTTP/1.1
Content-Type: application/json

{
  "email": "carol@example.com",
  "password": "hashed_pwd",
  "name": "Carol Chen"
}

Server assigns ID and creates resource:

HTTP/1.1 201 Created
Location: /users/456
Content-Type: application/json

{
  "user_id": 456,
  "email": "carol@example.com",
  "name": "Carol Chen",
  "created_at": "2025-01-15T14:30:00Z"
}

POST characteristics:

• POSTs to collection (/users not /users/456)
• Server assigns resource ID
• 201 Created status indicates success
• Location header contains new resource URL
• Not idempotent: Repeated POSTs create multiple resources

Why not idempotent:

POST /users {"email": "test@example.com"} → 201 Created, user_id=456

POST /users {"email": "test@example.com"} → 201 Created, user_id=789 (different resource!)

PUT replaces entire resource

Request sent to specific resource URL:

PUT /users/456 HTTP/1.1
Content-Type: application/json

{
  "email": "carol.new@example.com",
  "name": "Carol Chen",
  "is_active": false
}

Server replaces resource completely:

HTTP/1.1 200 OK

{
  "user_id": 456,
  "email": "carol.new@example.com",
  "name": "Carol Chen",
  "is_active": false,
  "updated_at": "2025-01-20T10:00:00Z"
}

PUT characteristics:

• PUTs to specific resource (/users/456)
• Client specifies resource ID
• Request body contains complete resource
• 200 OK with updated resource
• Idempotent: Multiple identical PUTs result in same state

PUT replaces entirely:

Missing fields in request are removed:

PUT /users/456 {"email": "new@example.com"}

Result: name field removed (entire resource replaced, not email alone)

Use PATCH for partial updates instead

Query parameters modify which resources are returned

Example: GET /flights?departure_airport=LAX

Path /flights identifies collection, departure_airport=LAX filters results

Query parameter syntax:

• Appended after ? in URL
• Key-value pairs: key=value
• Multiple parameters joined with &
• URL-encoded: Space → %20, special characters escaped

Filtering examples:

Single filter: GET /flights?departure_airport=LAX → Returns only flights departing from LAX

Multiple filters: GET /flights?departure_airport=LAX&arrival_airport=JFK&date=2025-02-15 → Returns LAX→JFK flights on specific date

Three-way filter: GET /flights?departure_airport=LAX&status=scheduled&aircraft_type=737 → Returns scheduled 737 flights from LAX

All filters are AND conditions - flight must match all criteria

Parameter validation returns 400 Bad Request:

Invalid value:

GET /flights?date=Feb-15-2025

HTTP/1.1 400 Bad Request

{
  "error": "Invalid date format",
  "parameter": "date",
  "expected_format": "YYYY-MM-DD"
}

Server validates parameters before database query

Sorting with parameters:

• GET /flights?sort=departure_time — Ascending order (default)
• GET /flights?sort=-departure_time — Descending order (minus prefix)
• GET /flights?sort=departure_airport,departure_time — Multiple fields (comma-separated)

Last example sorts LAX flights before JFK, then by time within each airport

Combining filters and sorting:

GET /flights?departure_airport=LAX&status=scheduled&sort=-departure_time

Returns scheduled LAX flights, most recent first

Query parameters keep URL structure clean while enabling flexible filtering

Collections grow beyond what a single response can efficiently carry

Without pagination: GET /flights → Returns 2,500 flights, 4MB response, 8 second load time

With pagination: GET /flights?limit=50&offset=0 → Returns 50 flights, 80KB response, 150ms load time

Offset-based pagination:

limit controls page size, offset controls starting position

• First page (flights 0-49): GET /flights?limit=50&offset=0
• Second page (flights 50-99): GET /flights?limit=50&offset=50
• Third page (flights 100-149): GET /flights?limit=50&offset=100

Formula: offset = page_number × limit

Pagination metadata in response:

{
  "flights": [...50 flight objects...],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 2500,
    "next": "/flights?limit=50&offset=50",
    "prev": null
  }
}

Pagination with filters:

GET /flights?departure_airport=LAX&limit=50&offset=0 → First 50 LAX flights GET /flights?departure_airport=LAX&limit=50&offset=50 → Next 50 LAX flights

Filters applied before pagination

Measured performance (2,500 flight collection):

• Full response: 8s, 4MB
• Paginated (50/page): 150ms, 80KB per page
• 53× faster initial load

Alternative strategies:

• Cursor-based: Position encoded in opaque token, stable under concurrent modifications, constant-time lookups regardless of page depth
• Page-based: ?page=2&per_page=50 — server calculates offset internally

Offset is simple but degrades at large offsets and produces inconsistent results when data changes between page fetches. Cursor-based pagination addresses both — covered in detail in API Specification.

Idempotent operation: Multiple identical requests have same effect as single request

GET - Idempotent and safe:

# Call once
response1 = requests.get('http://api/users/123')
user1 = response1.json()  # {"user_id": 123, "email": "alice@..."}

# Call again
response2 = requests.get('http://api/users/123')
user2 = response2.json()  # {"user_id": 123, "email": "alice@..."}

# Same result, no side effects
assert user1 == user2

PUT - Idempotent but not safe:

# Call once
requests.put('http://api/users/123',
             json={"email": "alice.new@example.com", "is_active": true})
# Result: email changed to alice.new@example.com

# Call again with same data
requests.put('http://api/users/123',
             json={"email": "alice.new@example.com", "is_active": true})
# Result: email still alice.new@example.com (no additional change)

# Multiple calls → same final state

DELETE - Idempotent:

# Call once
response1 = requests.delete('http://api/users/123')
# Response: 204 No Content, user deleted

# Call again
response2 = requests.delete('http://api/users/123')
# Response: 404 Not Found, user already deleted

# System in same state (user doesn't exist)

POST - Not idempotent:

# Call once
response1 = requests.post('http://api/users',
                          json={"email": "bob@example.com"})
# Response: 201 Created, user_id=456

# Call again with same data
response2 = requests.post('http://api/users',
                          json={"email": "bob@example.com"})
# Response: 201 Created, user_id=789 (different user!)

# Two users created - NOT idempotent

Idempotency matters for retries:

Network timeout scenario:

try:
    response = requests.post('http://api/bookings',
                            json={...},
                            timeout=5)
except requests.Timeout:
    # Did booking succeed or fail? Unknown!
    # Retry risks duplicate booking
    pass

Idempotency key pattern:

# Client generates unique request ID
idempotency_key = str(uuid.uuid4())

response = requests.post('http://api/bookings',
                        json={...},
                        headers={'Idempotency-Key': idempotency_key})

# If timeout, retry with same key
# Server sees duplicate key, returns original response
# Safe to retry POST operations

Server implementation:

if idempotency_key in cache:
    return cache[idempotency_key]  # Return cached response
else:
    result = create_booking(...)
    cache[idempotency_key] = result
    return result

REST constraint: Each request contains all information needed to process it

Stateful approach (violates REST):

# Login creates server-side session
POST /login
Body: {"email": "alice@example.com", "password": "..."}

Response:
HTTP/1.1 200 OK
Set-Cookie: session_id=abc123

# Server stores:
sessions['abc123'] = {
  'user_id': 123,
  'email': 'alice@example.com',
  'logged_in_at': '2025-01-15T10:00:00Z'
}

# Subsequent requests reference session
GET /bookings
Cookie: session_id=abc123

# Server looks up session['abc123'] to get user_id

Problems with server-side sessions:

• Server must store session for every active user
• 10K active users = 10K session objects in memory
• Load balancer must route all requests from user to same server
• Server restart loses all sessions
• Horizontal scaling requires session replication

Stateless approach (REST-compliant):

# Login returns token (JWT)
POST /login
Body: {"email": "alice@example.com", "password": "..."}

Response:
HTTP/1.1 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

# Token contains: {user_id: 123, email: "alice@...", exp: ...}
# Signed by server, cannot be forged

Stateless request:

# Every request includes complete authentication
GET /bookings
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Server decodes token to get user_id
# No session lookup needed

JWT (JSON Web Token) structure:

Header:
{
  "alg": "HS256",
  "typ": "JWT"
}

Payload:
{
  "user_id": 123,
  "email": "alice@example.com",
  "exp": 1705324800,  # Expiration timestamp
  "iat": 1705321200   # Issued at timestamp
}

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

Final token:
base64(header).base64(payload).signature

Benefits of stateless design:

• Server doesn’t store session data (no memory overhead)
• Any server can handle any request (no sticky sessions)
• Horizontal scaling trivial (add servers)
• Server restart doesn’t invalidate tokens
• Token validation: O(1) decode vs O(1) session lookup

Token expiration:

• Short-lived: 15 minutes (security)
• Refresh token: 30 days (obtain new access token)
• Client responsibility to manage token lifecycle

Statelessness: any server can handle any request — horizontal scaling without shared state

Python web frameworks for APIs:

• Flask: Minimal, explicit routing
• FastAPI: Modern, type-safe
• Django REST Framework: Full-featured

EE 547 uses Flask

Minimal abstractions make core concepts visible. Patterns transfer to FastAPI and Django REST.

Framework-agnostic concepts covered:

• Request/response flow
• URL routing and parameters
• Request data extraction
• Production deployment

Framework sits between HTTP server and handler code

Client
  ↓ HTTP Request
HTTP Server (gunicorn)
  ↓ WSGI
Flask Framework
  ↓ Calls
Handler Function
  ↓ Returns
Flask Framework
  ↓ WSGI
HTTP Server
  ↓ HTTP Response
Client

What Flask does:

1. Match URL to function
2. Parse incoming data
3. Call handler function
4. Build HTTP response

Handler implementation:

• Functions that process requests
• Business logic
• Return data

Connecting a URL to a function

from flask import Flask

app = Flask(__name__)

@app.route('/health')
def health_check():
    return {'status': 'healthy'}

What happens:

1. @app.route('/health') registers the route
2. Client sends: GET /health
3. Flask sees /health matches registered route
4. Flask calls health_check() function
5. Function returns dict
6. Flask converts to JSON response

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "healthy"}

Flask automatically:

• Sets status code to 200
• Sets Content-Type header
• Converts dict to JSON

Restricting which HTTP methods a route accepts

@app.route('/models', methods=['GET'])
def list_models():
    return {'models': [...]}

@app.route('/models', methods=['POST'])
def create_model():
    return {'id': 123}, 201

Same URL, different methods:

• GET /models → calls list_models()
• POST /models → calls create_model()
• PUT /models → 405 Method Not Allowed

Why separate by method:

• GET: Read data (list models)
• POST: Create data (new model)
• Different operations, different functions
• Clear separation of concerns

Default is GET only:

@app.route('/health')  # Only accepts GET
def health():
    return {'status': 'ok'}

Capturing values from the URL

@app.route('/models/<model_id>')
def get_model(model_id):
    return {'id': model_id}

URL: GET /models/42 Result: model_id = "42" (string)

Type conversion:

@app.route('/models/<int:model_id>')
def get_model(model_id):
    return {'id': model_id}

URL: GET /models/42 Result: model_id = 42 (integer)

URL: GET /models/abc Result: 404 Not Found (can’t convert to int)

Multiple parameters:

@app.route('/models/<int:model_id>/predictions/<pred_id>')
def get_prediction(model_id, pred_id):
    return {'model': model_id, 'prediction': pred_id}

URL: GET /models/42/predictions/xyz Result: model_id = 42, pred_id = "xyz"

Reading JSON from request body

from flask import request

@app.route('/predict', methods=['POST'])
def predict():
    data = request.json
    # data is dict: {'features': [1, 2, 3]}

    features = data['features']
    result = model.predict(features)

    return {'prediction': float(result)}

Client sends:

POST /predict
Content-Type: application/json

{"features": [1.2, 3.4, 5.6]}

Flask automatically:

• Checks Content-Type header
• Parses JSON string
• Creates Python dict
• Makes available as request.json

Safe access with get():

data = request.json
threshold = data.get('threshold', 0.5)  # Default if missing

Reading parameters from URL query string

@app.route('/models')
def list_models():
    # GET /models?limit=10&status=trained

    limit = request.args.get('limit', 100, type=int)
    # limit = 10 (converted to int)

    status = request.args.get('status')
    # status = "trained"

    models = fetch_models(limit=limit, status=status)
    return {'models': models}

Query string after ? in URL:

• Key-value pairs: key=value
• Multiple params: & separator
• /models?limit=10&status=trained

request.args.get() parameters:

• First arg: parameter name
• Second arg: default value if missing
• type=int: convert to integer

Without default:

status = request.args.get('status')  # None if missing

With default:

limit = request.args.get('limit', 100, type=int)  # 100 if missing

Reading HTTP headers

@app.route('/predict', methods=['POST'])
def predict():
    # Authorization header
    auth = request.headers.get('Authorization')
    # "Bearer eyJhbGci..."

    # Custom headers
    request_id = request.headers.get('X-Request-ID')

    # Content type
    content_type = request.headers.get('Content-Type')

    # Validate token
    if not auth:
        return {'error': 'Missing authorization'}, 401

    if not validate_token(auth):
        return {'error': 'Invalid token'}, 401

    # Process request
    return {'prediction': 0.87}

Common headers:

• Authorization: Auth tokens
• Content-Type: Body format
• X-Request-ID: Request tracking
• User-Agent: Client information

Headers case-insensitive:

request.headers.get('Content-Type')
request.headers.get('content-type')  # Same

Return dict → Flask converts to JSON

@app.route('/predict', methods=['POST'])
def predict():
    result = model.predict(request.json['features'])
    return {'prediction': float(result)}

Response Flask generates:

HTTP/1.1 200 OK
Content-Type: application/json

{"prediction": 0.87}

Flask automatically:

• Sets status code to 200 (success)
• Sets Content-Type to application/json
• Converts Python dict to JSON string
• Returns properly formatted HTTP response

This is the most common pattern:

• Simple and clean
• Works for most GET/PUT requests
• Default 200 status appropriate for success

Return tuple: (data, status_code)

@app.route('/models', methods=['POST'])
def create_model():
    model_id = save_model(request.json)
    return {'id': model_id}, 201

Response:

HTTP/1.1 201 Created
Content-Type: application/json

{"id": 42}

When to use different status codes:

201 Created - Resource successfully created (POST)

return {'id': new_id}, 201

204 No Content - Success but no data to return (DELETE)

return '', 204

404 Not Found - Resource doesn’t exist

return {'error': 'Model not found'}, 404

422 Unprocessable Entity - Validation failed

return {'error': 'Invalid input'}, 422

Return tuple: (data, status, headers)

@app.route('/models', methods=['POST'])
def create_model():
    model_id = save_model(request.json)

    return {'id': model_id}, 201, {
        'Location': f'/models/{model_id}',
        'X-Request-ID': request.headers.get('X-Request-ID')
    }

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /models/42
X-Request-ID: abc-123

{"id": 42}

Common response headers:

Location - URL of newly created resource

'Location': f'/models/{model_id}'

X-Request-ID - Echo back for tracking

'X-Request-ID': request.headers.get('X-Request-ID')

Cache-Control - Control caching

'Cache-Control': 'max-age=300'

Development server not for production

flask run

Problems:

• Single process, single thread
• Handles one request at a time
• No crash recovery
• Debug mode exposes code
• Poor performance under load

Example:

@app.route('/predict')
def predict():
    time.sleep(2)  # Prediction takes 2 seconds
    return {'result': 0.87}

With flask run:

• Request 1: 0-2 seconds
• Request 2: 2-4 seconds (waits)
• Request 3: 4-6 seconds (waits)
• All sequential, no concurrency

Production needs:

• Multiple worker processes
• Concurrent request handling
• Automatic crash recovery
• Process management

Single process means:

• One request blocks others
• No parallelism
• Poor resource usage
• Unacceptable for production

Gunicorn - Production WSGI server

pip install gunicorn
gunicorn --workers 4 --bind 0.0.0.0:5000 app:app

What this does:

• Starts 4 separate worker processes
• Each worker handles one request at a time
• 4 concurrent requests possible
• Load balanced across workers

Worker calculation:

workers = (CPU cores × 2) + 1

2-core machine → 5 workers 4-core machine → 9 workers

Same 2-second prediction with 4 workers:

• Requests 1-4: All start at 0s, finish at 2s
• Request 5: Starts at 2s when worker frees

4× improvement for concurrent requests

Configuration file:

# gunicorn.conf.py
workers = 4
bind = "0.0.0.0:5000"
timeout = 30

gunicorn -c gunicorn.conf.py app:app

Multiple workers = concurrent processing

Each worker is independent process

Flask serves static files synchronously, blocking the worker for the entire transfer

GET /static/model_weights.pkl  # 500MB file

What happens:

• Flask worker reads 500MB file
• Sends to client over network
• Worker blocked 30+ seconds
• 4 concurrent downloads = all workers blocked

Solution 1: Nginx serves static files

Nginx handles /static/* directly
Flask never sees these requests
Workers free for API calls

Solution 2: S3 redirect pattern

@app.route('/models/<model_id>/download')
def download_model(model_id):
    # Generate temporary S3 URL (expires in 1 hour)
    s3_url = generate_presigned_url(
        bucket='models',
        key=f'{model_id}.pkl',
        expires_in=3600
    )
    return redirect(s3_url)

Flow:

1. Client requests file from Flask
2. Flask returns 302 redirect to S3
3. Client downloads directly from S3
4. Flask worker free in <1ms

Use S3 redirect for: Large files (>10MB), model weights, datasets, user uploads

OpenAPI defines API structure in machine-readable format

Specification written in YAML or JSON, describes:

• Available endpoints and operations
• Request parameters and body schemas
• Response formats and status codes
• Authentication requirements
• Data types and constraints

Example specification for user endpoint:

openapi: 3.0.0
info:
  title: User Service API
  version: 2.1.0
paths:
  /users/{userId}:
    get:
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

components:
  schemas:
    User:
      type: object
      required: [user_id, email, is_active]
      properties:
        user_id: {type: integer}
        email: {type: string, format: email}
        is_active: {type: boolean}
        engagement_score: {type: number, minimum: 0, maximum: 100}

Specification serves multiple purposes:

1. Documentation source

• Swagger UI generates interactive docs
• Always synchronized with implementation
• Developers explore API without writing code

2. Validation layer

• Request validation against schema
• Response validation before sending
• Type checking and constraint enforcement

3. Code generation

• Server stubs with routing
• Client SDKs in multiple languages
• Type-safe API calls

4. Contract testing

• Verify implementation matches spec
• Detect breaking changes
• Test compliance automatically

Specification-first development:

Write spec → Generate code → Implement handlers

Ensures API design considered before implementation details

Alternative: Code-first

Write code → Generate spec from annotations

Easier to start, harder to maintain consistency

OpenAPI schemas define data structures with constraints

ML prediction endpoint schema:

paths:
  /models/{modelId}/predict:
    post:
      parameters:
        - name: modelId
          in: path
          schema: {type: string, pattern: '^[a-z0-9-]+$'}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [features, model_version]
              properties:
                features:
                  type: array
                  items: {type: number}
                  minItems: 10
                  maxItems: 10
                model_version:
                  type: string
                  enum: [v1.0, v1.1, v2.0]
                threshold:
                  type: number
                  minimum: 0.0
                  maximum: 1.0
                  default: 0.5
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                required: [prediction, confidence]
                properties:
                  prediction: {type: number}
                  confidence: {type: number, minimum: 0, maximum: 1}

Schema constraints validated automatically:

• Type checking: string vs number vs array
• Array length: exactly 10 features required
• Value ranges: threshold between 0 and 1
• Enum validation: model_version must match list
• Required fields: features and model_version mandatory

Invalid requests rejected before processing:

Missing required field:

POST /models/classifier-v2/predict
{"features": [1.2, 3.4, 5.6, 7.8, 9.0, 1.1, 2.2, 3.3, 4.4, 5.5]}

Response: 400 Bad Request
{
  "error": "Validation failed",
  "details": [{
    "field": "model_version",
    "message": "Required property missing"
  }]
}

Wrong array length:

POST /models/classifier-v2/predict
{"features": [1, 2, 3], "model_version": "v2.0"}

Response: 400 Bad Request
{
  "details": [{
    "field": "features",
    "message": "Array must contain 10 items, found 3"
  }]
}

Invalid enum value:

{"features": [...], "model_version": "v3.0"}

Response: 400 Bad Request
{
  "details": [{
    "field": "model_version",
    "message": "Value must be one of: v1.0, v1.1, v2.0"
  }]
}

Validation prevents:

• Type errors in application code
• Database constraint violations
• Model inference crashes
• Invalid computation results

Schema validation rejects bad requests in microseconds — before the server spends time on database queries or model inference

Single OpenAPI specification generates multiple artifacts

1. Interactive documentation (Swagger UI)

Browsable interface with:

• List of all endpoints grouped by resource
• Request/response examples
• Try-it-out functionality for live testing
• Schema definitions with types and constraints
• Authentication requirements

Developers test endpoints without writing client code

2. Server stubs

Generated code includes:

• Route definitions matching specification
• Request parsing and validation
• Response serialization
• Type hints (in typed languages)
• Handler function signatures

# Generated from OpenAPI spec
@app.route('/models/<model_id>/predict', methods=['POST'])
def predict_model(model_id: str):
    # Request already validated against schema
    body = request.json  # Type: PredictionRequest

    # Implement business logic here
    result = run_prediction(model_id, body['features'])

    # Response validated before sending
    return {'prediction': result, 'confidence': 0.87}

3. Client SDKs

Type-safe client libraries:

# Generated Python client
from api_client import UserServiceClient

client = UserServiceClient(base_url='https://api.example.com')

# Method signatures from spec
user = client.get_user(user_id=123)  # Type: User
print(user.email)  # IDE autocomplete knows fields

# Type checker catches errors
client.get_user(user_id="abc")  # Error: expected int

4. Request validation middleware

Automatically generated validators:

# Validates before handler executes
def validate_request(spec):
    def decorator(f):
        def wrapper(*args, **kwargs):
            # Check request matches spec
            errors = validate_against_schema(
                request,
                spec['paths'][request.path]
            )
            if errors:
                return {'error': errors}, 400
            return f(*args, **kwargs)
        return wrapper
    return decorator

5. Mock servers

Generate mock API from specification:

• Returns example responses
• Validates request format
• Enables frontend development before backend complete

Code generation tools:

• OpenAPI Generator: 40+ language targets
• Swagger Codegen: Server and client generation
• Prism: Mock server from specification
• Redoc: Alternative documentation renderer

Specification as single source of truth:

Change spec → Regenerate all artifacts

Documentation, validation, and client code stay synchronized

Manual maintenance alternative:

• Write documentation separately (becomes outdated)
• Write validation logic per endpoint (inconsistent)
• Manually create client libraries (error-prone)
• Update all three when API changes (forgotten)

Machine-readable specification prevents divergence

APIs evolve but clients update slowly

Version placement options:

URL path versioning (most common):

GET /v1/users/123
GET /v2/users/123

Advantages:

• Version immediately visible in URL
• Easy to route in load balancer
• Clear in logs and monitoring

Disadvantages:

• URL changes with version
• Resource “same” user has different URLs

Header versioning:

GET /users/123
Accept: application/vnd.api.v1+json

GET /users/123
Accept: application/vnd.api.v2+json

Advantages:

• URLs remain stable
• Content negotiation pattern

Disadvantages:

• Version not visible in URL
• Harder to test in browser
• Requires header inspection

Custom header:

GET /users/123
API-Version: 1

GET /users/123
API-Version: 2

Similar trade-offs to Accept header

Query parameter (not recommended):

GET /users/123?version=1
GET /users/123?version=2

Disadvantages:

• Mixes version with filtering parameters
• Caching issues (query params affect cache key)

Version granularity:

Major versions (breaking changes):

• v1 → v2: Field removed or renamed
• v2 → v3: Response structure changed
• Requires separate implementation

Minor versions (additions):

• v2.0 → v2.1: New optional field added
• v2.1 → v2.2: New endpoint added
• Backward compatible within major version

Semantic versioning pattern:

MAJOR.MINOR.PATCH

• MAJOR: Breaking changes (v1 → v2)
• MINOR: New features, backward compatible (v2.0 → v2.1)
• PATCH: Bug fixes (v2.1.0 → v2.1.1)

When to increment major version:

• Removing endpoint
• Removing required field from response
• Adding required field to request
• Changing field type
• Renaming field
• Changing authentication method

Backward compatible additions:

• New optional request field
• New field in response (clients ignore unknown)
• New endpoint
• New optional query parameter
• New HTTP status code for new error case

Parallel version support:

Both versions active simultaneously:

@app.route('/v1/users/<id>')
def get_user_v1(id):
    user = fetch_user(id)
    return {'user': id, 'active': user.is_active}

@app.route('/v2/users/<id>')
def get_user_v2(id):
    user = fetch_user(id)
    return {
        'user_id': id,  # Renamed
        'is_active': user.is_active,
        'created_at': user.created_at  # New field
    }

Breaking change: Modification that causes existing clients to fail

Common breaking changes:

Field removal:

// v1 response
{"user_id": 123, "email": "alice@example.com", "phone": "+1-555-0100"}

// v2 response
{"user_id": 123, "email": "alice@example.com"}
// phone field removed

Client code accessing response['phone'] raises KeyError

Field rename:

// v1: {"created": "2024-01-15"}
// v2: {"created_at": "2024-01-15"}

Client parsing created field receives KeyError

Type change:

// v1: {"count": "42"}    (string)
// v2: {"count": 42}       (number)

Client expecting string, performs string operations on number → TypeError

New required field:

// v1 request
POST /bookings
{"flight_id": 456, "user_id": 123}

// v2 request (requires seat_class)
POST /bookings
{"flight_id": 456, "user_id": 123, "seat_class": "economy"}

Old clients missing seat_class → 400 Bad Request

Status code change:

// v1: Returns 200 OK when user not found (empty result)
// v2: Returns 404 Not Found when user not found

Client checking status == 200 for success misses 404 case

Non-breaking changes (backward compatible):

Adding optional field to response:

// v1 response
{"user_id": 123, "email": "alice@example.com"}

// v2 response
{"user_id": 123, "email": "alice@example.com",
 "created_at": "2024-01-15"}

Old clients ignore unknown created_at field

Adding optional request parameter:

// v1: GET /flights?departure=LAX
// v2: GET /flights?departure=LAX&max_price=500

Old clients don’t send max_price, server uses default behavior

Adding new endpoint:

// v1: GET /users, POST /users
// v2: GET /users, POST /users, GET /users/search

Old clients unaware of /users/search, continue using existing endpoints

Adding new HTTP method to existing endpoint:

// v1: GET /users/123
// v2: GET /users/123, PATCH /users/123

Old clients only use GET, PATCH addition doesn’t affect them

Deprecation headers indicate future removal:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 31 Dec 2025 23:59:59 GMT
Link: </v2/users/123>; rel="successor-version"

Clients warned field or endpoint will be removed

Contract testing prevents breaking changes:

def test_v1_user_response_format():
    """Verify v1 response format unchanged"""
    response = api_client.get_user_v1(123)

    assert 'user_id' in response
    assert 'email' in response
    assert isinstance(response['user_id'], int)
    assert isinstance(response['email'], str)

Test fails if response structure changes, preventing accidental breaking changes

Removing old API versions requires full client migration

Parallel operation is mandatory:

• Deploy v2 alongside v1
• Existing clients continue on v1 uninterrupted
• New clients adopt v2 immediately
• Server maintains both implementations simultaneously

Monitor adoption via request logs:

SELECT version, COUNT(*) as requests
FROM api_logs
WHERE timestamp > NOW() - INTERVAL '7 days'
GROUP BY version;

-- v1: 234,567 requests (65%)
-- v2: 126,433 requests (35%)

Cannot remove v1 until 0% traffic remains

Signal deprecation through HTTP headers:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Mon, 15 Sep 2025 23:59:59 GMT
Link: </docs/v2-migration>; rel="deprecation-policy"

Clients can programmatically detect pending removal

Gradual enforcement before shutdown:

• Make v1 read-only: GET continues, mutations return 410 Gone
• Identify remaining clients by API key / User-Agent
• Contact directly for migration assistance

Clients that block migration:

SELECT client_id, COUNT(*) as requests
FROM api_logs
WHERE version = 'v1'
  AND timestamp > NOW() - INTERVAL '7 days'
GROUP BY client_id
ORDER BY requests DESC;

-- batch-job-1: 8,234 (automated, no owner)
-- mobile-app: 2,109 (old app version)
-- partner-api: 1,876 (quarterly release cycle)
-- unknown: 234 (API key ownership lost)

Forgotten batch jobs, outdated mobile apps, and third-party integrations with slow release cycles are the typical blockers

Final shutdown returns 410 Gone:

HTTP/1.1 410 Gone

{
  "error": "API v1 has been retired",
  "migration_guide": "/docs/v1-to-v2",
  "support": "api-support@example.com"
}

Cost of maintaining parallel versions:

• Duplicate code, tests, and security patches
• Monitoring and support for both
• Roughly doubles development and testing burden during overlap

Internal API migrations can take months; external deprecations can stretch considerably longer

Structured errors provide actionable information

Basic error response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed"
  }
}

Detailed validation errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "features[3]",
        "value": "NaN",
        "constraint": "type",
        "message": "Must be a number"
      },
      {
        "field": "threshold",
        "value": 1.5,
        "constraint": "maximum",
        "message": "Must be at most 1.0"
      }
    ]
  }
}

Rate limit error with retry information:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "limit": 1000,
    "remaining": 0,
    "reset_at": "2025-01-15T15:00:00Z",
    "retry_after": 600
  }
}

Resource not found with suggestions:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Model 'classifier-xyz' not found",
    "resource_type": "model",
    "resource_id": "classifier-xyz",
    "suggestions": [
      "Use GET /models to list available models",
      "Check model_id spelling"
    ]
  }
}

Error response components:

1. Machine-readable code

Enables programmatic handling:

if response.status_code == 400:
    error = response.json()['error']

    if error['code'] == 'VALIDATION_ERROR':
        # Fix validation issues
        for detail in error['details']:
            log.warning(f"Field {detail['field']}: {detail['message']}")

    elif error['code'] == 'RATE_LIMIT_EXCEEDED':
        # Wait and retry
        time.sleep(error['retry_after'])

2. Human-readable message

For developer debugging and logs

3. Context-specific details

Field-level errors for validation failures

4. Actionable information

Rate limits include reset time and retry delay

5. Request correlation

{
  "error": {...},
  "request_id": "7f3c6b2a-5d9e-4f8b",
  "timestamp": "2025-01-15T14:35:22Z"
}

Include in support tickets for log correlation

6. Documentation links

{
  "error": {...},
  "documentation": "https://api.example.com/docs/errors/validation"
}

Error code categories:

• VALIDATION_ERROR: Client sent invalid data
• AUTHENTICATION_ERROR: Token missing or invalid
• AUTHORIZATION_ERROR: Valid token, insufficient permissions
• RATE_LIMIT_EXCEEDED: Too many requests
• RESOURCE_NOT_FOUND: Requested resource doesn’t exist
• CONFLICT: Operation conflicts with current state
• SERVER_ERROR: Internal server failure

Consistent error structure across all endpoints

Large collections require pagination

Collection with 2,500 users:

Without pagination: GET /users

• Returns all 2,500 users
• Response size: 3.8 MB
• Load time: 6-8 seconds
• Client memory: Entire collection

With pagination: GET /users?limit=50&offset=0

• Returns 50 users
• Response size: 76 KB (50× smaller)
• Load time: 120ms (50× faster)
• Client memory: Current page only

Offset-based pagination parameters:

limit: Number of items per page (page size) offset: Number of items to skip (starting position)

Fetching pages:

Page 1 (users 1-50):

GET /users?limit=50&offset=0

Page 2 (users 51-100):

GET /users?limit=50&offset=50

Page 3 (users 101-150):

GET /users?limit=50&offset=100

Formula: offset = (page_number - 1) × limit

Pagination metadata in response:

{
  "users": [
    {"user_id": 1, "email": "alice@example.com", ...},
    {"user_id": 2, "email": "bob@example.com", ...},
    ...
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 2500,
    "has_more": true,
    "next": "/users?limit=50&offset=50",
    "previous": null
  }
}

Offset pagination with filters:

GET /users?status=active&limit=50&offset=0

Filter applied before pagination:

1. Query users where status=‘active’ (1,200 matching)
2. Skip first 0 users
3. Return next 50 users

{
  "users": [...50 active users...],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1200,  // Total matching filter
    "next": "/users?status=active&limit=50&offset=50"
  }
}

Offset pagination advantages:

• Simple to implement
• Easy to understand
• Can jump to arbitrary page
• Total count available

Offset pagination limitations:

1. Performance degrades with large offsets

Database query: SELECT * FROM users LIMIT 50 OFFSET 10000

Must scan 10,000 rows before returning 50

• Page 1 (offset=0): 15ms
• Page 100 (offset=5000): 340ms
• Page 1000 (offset=50000): 4200ms

2. Inconsistent results during modifications

Client requests page 1 (users 1-50) User 25 gets deleted Client requests page 2 (offset=50)

Receives users 51-100 (previously users 52-101) User 51 never seen by client

3. Duplicate results with insertions

Client requests page 1 (users 1-50) New user inserted at position 10 Client requests page 2 (offset=50)

Receives users 51-100 (previously users 50-99) User 50 appears on both pages

Cursor-based pagination solves these issues

Cursor encodes position in result set

Instead of numeric offset, use opaque cursor token

Initial request:

GET /users?limit=50

Response with cursor:

{
  "users": [
    {"user_id": 1, ...},
    {"user_id": 2, ...},
    ...
    {"user_id": 50, ...}
  ],
  "pagination": {
    "limit": 50,
    "next_cursor": "eyJ1c2VyX2lkIjo1MH0=",
    "has_more": true
  }
}

Next page request:

GET /users?limit=50&cursor=eyJ1c2VyX2lkIjo1MH0=

Cursor is base64-encoded JSON: {"user_id": 50}

Database query using cursor:

-- Without cursor (first page)
SELECT * FROM users ORDER BY user_id LIMIT 50;

-- With cursor (subsequent pages)
SELECT * FROM users
WHERE user_id > 50
ORDER BY user_id
LIMIT 50;

No OFFSET clause - uses indexed WHERE condition

Cursor for different sort orders:

Sort by created_at descending:

{
  "cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQxMDozMDowMFoiLCJ1c2VyX2lkIjo1MH0="
}

Decoded: {"created_at": "2025-01-15T10:30:00Z", "user_id": 50}

Include user_id for tie-breaking when timestamps equal

Cursor pagination advantages:

1. Consistent performance

Direct index lookup, no scanning:

• Page 1: 15ms
• Page 100: 15ms
• Page 1000: 15ms (constant time)

2. Stable results during modifications

Client requests page 1 with cursor User 25 gets deleted Client requests page 2 using cursor

Cursor points to user_id > 50, deletion of user 25 doesn’t affect next page

3. No duplicate results from insertions

Cursor maintains position relative to sorted order, new insertions don’t cause duplicates

Cursor pagination limitations:

Cannot jump to arbitrary page

No “go to page 50” - must traverse sequentially

Cannot display total page count

Computing total requires full count query (expensive)

Cursor must be opaque to client

// Bad: Exposing internal structure
GET /users?after_id=50

// Good: Opaque cursor
GET /users?cursor=eyJ1c2VyX2lkIjo1MH0=

Allows server to change cursor format without breaking clients

When to use each approach:

Offset pagination:

• Need page numbers (UI with page selector)
• Need total count
• Data rarely changes
• Small to medium collections

Cursor pagination:

• Large collections (millions of rows)
• Data frequently updated
• Mobile apps (efficient, consistent)
• Infinite scroll UX

Many APIs support both: limit/offset for random access, limit/cursor for efficient traversal

June 2012: 6.5 million LinkedIn password hashes stolen^[1]

What LinkedIn did:

-- Stored password hashes (not plaintext) ✓
SELECT user_id, email, password_hash FROM users;

-- But used SHA-1 without salt ✗
password_hash = SHA1(password)

What attackers did:

1. Built password dictionary (10 million common passwords)
2. Computed hashes once:

common_hashes = {
    SHA1("password123"): "password123",
    SHA1("123456"): "123456",
    # ... 10 million entries
}

3. Searched stolen database:

for hash in stolen_hashes:
    if hash in common_hashes:
        compromised.append(common_hashes[hash])

Reported result: ~90% of passwords cracked within 72 hours

Why it failed:

• SHA-1 designed for speed: GPU computes 10 billion hashes/second
• No salt: Same password → same hash
• One computation → thousands of accounts compromised

Same password “123456” compromised 753,000 accounts simultaneously

LinkedIn’s breach shows authentication failures cascade across systems

ML API requires authentication to prevent unauthorized access:

DELETE /models/production/v2
# Who sent this? Can they delete production models?

Every API request needs to answer two questions:

1. Who is making this request? (Authentication)
2. Can they perform this action? (Authorization)

In a single process, identity is implicit:

def delete_file(filepath):
    # Running as OS user 'alice'
    # OS checks if alice can delete filepath
    os.remove(filepath)

In distributed systems, identity must be explicit:

def handle_delete_request(request):
    # Who sent this HTTP request?
    user = authenticate(request)  # Extract identity
    
    # Can they delete this file?
    if not authorize(user, 'delete', filepath):
        return 403
    
    delete_file(filepath)

HTTP is stateless - no memory between requests:

• No persistent connection to maintain identity
• Each request independent
• Must prove identity every time

Three approaches to maintaining identity across requests:

1. Include credentials every request (HTTP Basic Auth)
2. Create server-side session (Cookie-based)
3. Issue cryptographic proof (Token-based)

Each approach makes different trade-offs between security, scalability, and complexity.

Authentication transforms a secret into verified identity

Step 1: User provides credentials

POST /login
{"email": "alice@example.com", "password": "secret123"}

Step 2: Server verifies against stored credentials

def authenticate(email, password):
    user = db.query("SELECT * FROM users WHERE email = ?", email)
    if verify_password(password, user.password_hash):
        return user.id  # Identity established
    return None

Step 3: Server issues proof of authentication

# Option A: Server-side session
session_id = generate_random_id()
sessions[session_id] = user_id
return {"session_id": session_id}

# Option B: Cryptographic token
token = jwt.encode({"user_id": user_id, "exp": time() + 3600})
return {"token": token}

Password storage determines breach impact:

Never store plaintext passwords:

-- CATASTROPHIC: Database breach exposes all passwords
SELECT * FROM users WHERE password = 'secret123'

Store cryptographic hashes instead:

-- Safe: Cannot reverse hash to get password
SELECT * FROM users WHERE email = 'alice@example.com'
-- Then verify: hash(provided_password) == stored_hash

LinkedIn used SHA-1 hashing - why wasn’t that enough?

First, understand why plaintext is catastrophic:

Database breach with plaintext passwords:

SELECT email, password FROM users LIMIT 3;
-- alice@example.com | secret123
-- bob@example.com   | secret123  
-- carol@example.com | password1

All accounts immediately compromised.

Hash functions provide one-way transformation:

hash("secret123") → "5994471abb01112afcc18159f6cc74b4f511b99806da59b3caf5a9c173cacfc5"

Cannot reverse: hash → original password (computationally infeasible)

Asymmetry favors attackers:

Legitimate use: Verify one password for one user

# Single hash computation: < 1ms
if hash(provided_password) == stored_hash:
    authenticate_user()

Attack: Try millions of passwords against all users

# Attacker with stolen hash database
common_passwords = ["password", "123456", "secret123", ...]
for password in common_passwords:  # 10 million
    test_hash = hash(password)
    for stored_hash in database:  # 100,000 users
        if test_hash == stored_hash:
            compromised.append(...)

Solution: Make hashing deliberately slow

• SHA-1 (LinkedIn’s mistake): Designed for speed → 10 billion/second on GPU
• bcrypt: Designed for passwords → 10/second on GPU
• Time difference: 1 billion× slower

This is why LinkedIn’s passwords fell in 72 hours - SHA-1 allowed rapid dictionary attacks.

This asymmetry favors defenders over attackers.

LinkedIn’s second mistake: No salt

Even with slow hashing, common passwords create identical hashes:

Without salt, all users with “password123” have same hash:

hash("password123") → "ef92b778bafe771e89245b89ecb..."
# Database search finds 1,847 users with this hash
# All compromised with single hash computation

Salt: Random value unique to each user

def create_user(email, password):
    salt = generate_random_bytes(16)  # Unique per user
    password_hash = hash(salt + password)
    db.store(email, salt, password_hash)

Now identical passwords produce different hashes:

# User 1
salt1 = "a1b2c3d4..."
hash("a1b2c3d4..." + "password123") → "7f3c6b2a..."

# User 2  
salt2 = "e5f6g7h8..."
hash("e5f6g7h8..." + "password123") → "92a8b7c6..."

# Different hashes despite same password

Impact on attack strategy:

Without salt: One computation compromises all instances

target_hash = "ef92b778..."
if computed_hash == target_hash:
    # Found password for ALL users with this hash

With salt: Must attack each user individually

for user in users:
    for password in dictionary:
        if hash(user.salt + password) == user.hash:
            # Found password for ONE user only

Salt is not secret - stored with hash, prevents mass attacks not targeted ones

With salt, LinkedIn’s 753,000 “123456” users would each need individual attacks

Combining defenses: Slow hashing + Salt + Adaptive work factor

bcrypt’s configurable work factor scales with hardware improvements:

# Work factor determines iteration count: 2^factor
bcrypt.gensalt(10)  # 2^10 = 1,024 iterations (2010)
bcrypt.gensalt(12)  # 2^12 = 4,096 iterations (2020)  
bcrypt.gensalt(14)  # 2^14 = 16,384 iterations (2030)

Each increment doubles computation time:

Balancing security and usability:

def choose_work_factor():
    # Target: 250ms computation time
    test_password = b"benchmark"
    
    for factor in range(10, 15):
        start = time.time()
        bcrypt.hashpw(test_password, bcrypt.gensalt(factor))
        duration = time.time() - start
        
        if duration > 0.250:  # 250ms target
            return factor
    
    return 14  # Maximum reasonable factor

Moore’s Law compensation:

• Computing power doubles every 2 years
• Increase work factor by 1 every 2 years
• Maintains constant security margin

Security parameter improves over time without code changes

Server sessions: Centralized state

# Login creates session in shared store
session_id = generate_uuid()
redis.set(f"session:{session_id}", {
    "user_id": 123,
    "created": timestamp,
    "permissions": ["read", "write"]
})
response.set_cookie("session_id", session_id)

# Every request requires lookup
def handle_request(request):
    session_id = request.cookies.get("session_id")
    session = redis.get(f"session:{session_id}")  # Network call
    if not session:
        return 401

Tokens: Distributed state

# Login creates self-contained token
payload = {
    "user_id": 123,
    "exp": timestamp + 3600,
    "permissions": ["read", "write"]
}
token = jwt.encode(payload, SECRET_KEY)
return {"token": token}

# Every request validates locally
def handle_request(request):
    token = request.headers["Authorization"].split(" ")[1]
    payload = jwt.decode(token, SECRET_KEY)  # CPU only
    # No network call required

Trade-offs in practice:

Authentication establishes identity; authorization determines capabilities

def process_request(request):
    # Step 1: Who are you? (Authentication)
    user_id = validate_token(request.headers['Authorization'])
    if not user_id:
        return 401  # Unauthorized - don't know who you are
    
    # Step 2: What can you do? (Authorization)
    resource = request.path  # e.g., /models/123
    action = request.method   # e.g., DELETE
    
    if not has_permission(user_id, resource, action):
        return 403  # Forbidden - know who you are, can't do this
    
    # Step 3: Execute
    return perform_action(resource, action)

Three authorization models:

1. Role-Based (RBAC): Users have roles, roles have permissions

user.roles = ["developer", "viewer"]
role_permissions = {
    "developer": ["read", "write", "deploy"],
    "viewer": ["read"],
    "admin": ["read", "write", "deploy", "delete"]
}
# Can user deploy? Check if any role has permission

2. Attribute-Based (ABAC): Decisions based on attributes

can_access = (
    user.department == resource.department and
    user.clearance_level >= resource.sensitivity and
    current_time in user.work_hours
)

3. Resource-Based: Users own resources

if resource.owner_id == user_id:
    return FULL_ACCESS
elif user_id in resource.shared_with:
    return READ_ONLY
else:
    return NO_ACCESS

Tokens can’t be recalled after issuing:

Once issued, JWT remains valid until expiration:

token_payload = {
    "user_id": 123,
    "exp": time() + 3600,  # Valid for 1 hour
    "scopes": ["read:data", "write:data", "delete:data"]
}

Employee terminated at 2:00 PM:

• Token issued: 1:30 PM
• Token expires: 2:30 PM
• Problem: 30 minutes of unauthorized access

Three approaches to bounded revocation:

1. Short-lived access tokens (15 minutes)

access_token = create_token(expires_in=15*60)
refresh_token = create_token(expires_in=30*24*60*60)

# After termination, refresh fails
def refresh():
    if user_terminated(refresh_token.user_id):
        return 401  # No new access token
    return create_access_token()