api-design-patternslisted
Install: claude install-skill phamlongh230-lgtm/yamtam-engine
# API Design Patterns
## Versioning
```python
# URL versioning — simplest, most visible
# /v1/users, /v2/users
from fastapi import APIRouter, FastAPI
app = FastAPI()
v1 = APIRouter(prefix="/v1")
v2 = APIRouter(prefix="/v2")
@v1.get("/users/{user_id}")
async def get_user_v1(user_id: str) -> UserV1Response: ...
@v2.get("/users/{user_id}")
async def get_user_v2(user_id: str) -> UserV2Response: ...
app.include_router(v1)
app.include_router(v2)
```
## Consistent Error Response Shape
```python
from pydantic import BaseModel
from fastapi import Request
from fastapi.responses import JSONResponse
from typing import Any
class ErrorResponse(BaseModel):
error: str # machine-readable code
message: str # human-readable
detail: Any = None # additional context
request_id: str = "" # for support
# Global exception handler
@app.exception_handler(AppError)
async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
status_map = {
"NOT_FOUND": 404,
"VALIDATION_ERROR": 422,
"UNAUTHORIZED": 401,
"FORBIDDEN": 403,
"CONFLICT": 409,
}
return JSONResponse(
status_code=status_map.get(exc.code, 500),
content=ErrorResponse(
error=exc.code,
message=str(exc),
request_id=request.headers.get("X-Request-ID", ""),
).model_dump(),
)
```
## Pagination: Cursor-Based
```python
from pydantic import BaseModel
from typing import Generic,