Python API Development

Modern patterns for building production-ready APIs with FastAPI and Flask.

Decision Matrix: FastAPI vs Flask

General guidance:

• Use FastAPI when: New projects, async needed, want auto-docs, type safety important
• Use Flask when: Simple apps, team knows Flask, sync-only fine, want simplicity

FastAPI Patterns

Basic API Structure

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.get("/")
def read_root():
    return {"message": "Hello World"}

@app.post("/items/")
def create_item(item: Item):
    return item

Pydantic Models for Validation

from pydantic import BaseModel, Field

class User(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: str
    age: int = Field(..., ge=0, le=150)

See pydantic-validation.md for:

• Custom validators
• Model inheritance
• Nested models

Dependency Injection

from fastapi import Depends

def get_db():
    db = Database()
    try:
        yield db
    finally:
        db.close()

@app.get("/items/")
def read_items(db = Depends(get_db)):
    return db.get_items()

See dependency-injection-patterns.md for:

• Class-based dependencies
• Dependency override (testing)
• Sub-dependencies

Async Endpoints

@app.get("/data/")
async def get_data():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.example.com/data")
        return response.json()

See async-api-patterns.md for:

• When async helps
• Database async patterns
• Concurrent request handling

Flask Patterns

Basic Flask API

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/users/<int:user_id>")
def get_user(user_id):
    user = db.get_user(user_id)
    return jsonify(user)

See flask-patterns.md for:

• Application factory pattern
• Flask extensions
• Request hooks

API Design Best Practices

RESTful Conventions

GET    /api/users          # List users
POST   /api/users          # Create user
GET    /api/users/123      # Get user
PUT    /api/users/123      # Update user
DELETE /api/users/123      # Delete user

Response Structure

# Success
{"data": {...}, "meta": {"timestamp": "..."}}

# Error
{"error": {"code": "...", "message": "...", "details": [...]}}

Authentication Patterns

See authentication-patterns.md for:

• JWT with FastAPI
• OAuth2 with FastAPI
• API keys
• Session-based (Flask)

Anti-Patterns to Avoid

source: FastAPI docs, Flask docs, REST API best practices