Your API will change. How you handle that change determines whether clients curse your name or barely notice. The Three Approaches 1. URL Path Versioning G G E E T T v 1 2 / / u u s s e e r r s s / / 1 1 2 2 3 3 Pros: ...
Your API will change. Features will be added, mistakes will be corrected, and sometimes you’ll need to break things. The question isn’t whether to version — it’s how. Why Version? Breaking changes are changes that make existing clients fail: Removing a field from a response Changing a field’s type (string → integer) Requiring a new parameter Changing the meaning of a value Removing an endpoint Without versioning, every change risks breaking someone’s integration. With versioning, you can evolve the API while giving clients time to adapt. ...
Every API eventually needs to return more data than fits in a single response. How you handle that pagination affects performance, reliability, and developer experience. Let’s look at the common patterns, their tradeoffs, and when to use each. The Three Main Approaches 1. Offset Pagination The classic approach: skip N records, return M records. G G G E E E T T T / / / a a a p p p i i i / / / i i i t t t e e e m m m s s s ? ? ? o o o f f f f f f s s s e e e t t t = = = 0 2 4 & 0 0 l & & i l l m i i i m m t i i = t t 2 = = 0 2 2 0 0 # # # P P P a a a g g g e e e 1 2 3 Implementation: ...
Your API will be called wrong. Clients will send garbage. Load will spike unexpectedly. Authentication will be misconfigured. The question isn’t whether these things happen — it’s whether your API degrades gracefully or explodes. Here’s how to build APIs that survive contact with the real world. Input Validation: Trust Nothing Every field, every header, every query parameter is hostile until proven otherwise. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 from pydantic import BaseModel, Field, validator from typing import Optional import re class CreateUserRequest(BaseModel): email: str = Field(..., max_length=254) name: str = Field(..., min_length=1, max_length=100) age: Optional[int] = Field(None, ge=0, le=150) @validator('email') def validate_email(cls, v): # Don't just regex — actually validate structure if not re.match(r'^[^@]+@[^@]+\.[^@]+$', v): raise ValueError('Invalid email format') return v.lower().strip() @validator('name') def sanitize_name(cls, v): # Remove control characters, normalize whitespace v = re.sub(r'[\x00-\x1f\x7f-\x9f]', '', v) return ' '.join(v.split()) Key principles: ...
APIs evolve. Fields get renamed, endpoints change, entire resources get restructured. The question isn’t whether to version your API—it’s how to do it without breaking every client that depends on you. Versioning Strategies 1. URL Path Versioning The most visible approach—version is part of the URL: G G E E T T / / a a p p i i / / v 1 2 / / u u s s e e r r s s / / 1 1 2 2 3 3 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 from fastapi import FastAPI, APIRouter app = FastAPI() # Version 1 v1_router = APIRouter(prefix="/api/v1") @v1_router.get("/users/{user_id}") async def get_user_v1(user_id: int): return { "id": user_id, "name": "John Doe", "email": "john@example.com" } # Version 2 - restructured response v2_router = APIRouter(prefix="/api/v2") @v2_router.get("/users/{user_id}") async def get_user_v2(user_id: int): return { "id": user_id, "profile": { "name": "John Doe", "email": "john@example.com" }, "metadata": { "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-02-11T00:00:00Z" } } app.include_router(v1_router) app.include_router(v2_router) Pros: Explicit, easy to understand, easy to route Cons: URLs change between versions, harder to maintain multiple versions ...
Practical REST API design patterns — naming conventions, versioning strategies, error handling, and pagination that scales.