Recap — Sync vs Async Endpoints

# Sync vs Async Endpoints FastAPI supports both async and sync endpoints. Understanding when to use each matters for performance and correctness. ## How FastAPI handles each ### `async def` endpoint Runs in the event loop. Must use `await` for I/O. Blocking calls inside (like `time.sleep`, `requests.get`) freeze the event loop. ```python @app.get("/users") async def get_users(): async with httpx.AsyncClient() as client: response = await client.get("https://api.example.com/users") return response.json() ``` ### Plain `def` endpoint Runs in a thread pool. FastAPI doesn't block the event loop. Can use sync libraries safely. ```python @app.get("/users") def get_users(): response = requests.get("https://api.example.com/users") # sync OK here return response.json() ``` ## When to use async - Your endpoint awaits I/O frequently (multiple HTTP calls, async DB). - You use async-aware libraries (httpx, asyncpg, async ORM). - High concurrency required (1000s of simultaneous connections). ## When sync is fine - Endpoint does a single DB query or one HTTP call. - Using sync libraries (psycopg2, requests, SQLAlchemy non-async). - Simple CRUD apps; small to medium scale. FastAPI's threadpool for sync endpoints handles 100s of concurrent requests fine. Don't over-optimize. ## The trap: async + sync I/O ```python @app.get("/users") async def get_users(): response = requests.get("https://api.example.com/users") # BAD: sync in async # This blocks the event loop. Other async endpoints stall. return response.json() ``` Either use async libraries OR offload to thread: ```python @app.get("/users") async def get_users(): response = await asyncio.to_thread(requests.get, "https://api.example.com/users") return response.json() ``` Or just make it sync def. ## Async library ecosystem | For | Sync | Async | |---|---|---| | HTTP client | requests | httpx, aiohttp | | Postgres | psycopg2 | asyncpg, psycopg 3 (async mode) | | Redis | redis | redis.asyncio | | ORM (SQLAlchemy) | sync | async via `create_async_engine` | | MongoDB | pymongo | motor | | File I/O | open() | aiofiles | For mixed workloads, you can mix: ```python @app.get("/dashboard") async def dashboard(): # async DB query users = await db.execute(...) # async HTTP call stats = await httpx_client.get(...) return {"users": users, "stats": stats} ``` ## Async SQLAlchemy ```python from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession engine = create_async_engine("postgresql+asyncpg://...") AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession) async def get_db(): async with AsyncSessionLocal() as session: yield session @app.get("/users") async def get_users(db: AsyncSession = Depends(get_db)): result = await db.execute(select(User)) return result.scalars().all() ``` Async SQLAlchemy is real but adds complexity. For most apps, sync SQLAlchemy + sync def endpoints is simpler and adequate. ## Background tasks with async Async endpoints can fire-and-forget background work: ```python import asyncio @app.post("/upload") async def upload(file: UploadFile): data = await file.read() # Start background task; don't await asyncio.create_task(process_async(data)) return {"status": "uploaded"} async def process_async(data): # heavy work pass ``` Endpoint returns immediately; processing continues. (For more robust background work, see Module 3's lesson on Celery/ARQ.) ## Performance comparison For an endpoint that makes 5 HTTP calls: - Sync: ~5x HTTP latency (serial). 500ms per request. - Async with `asyncio.gather`: 1x HTTP latency. 100ms per request. For an endpoint that does one DB query: - Sync: fine. ~10ms. - Async: also fine. ~10ms. Async wins clearly when you have multiple I/O operations to do. ## Common mistakes 1. **`async def` + sync I/O.** Blocks event loop. Worst of both worlds. 2. **`def` + heavy CPU work.** Blocks the threadpool slot. Use multiprocessing. 3. **All endpoints async without async libraries.** Cargo-cult; sync would be fine. 4. **Forgetting await.** `client.get()` returns coroutine; needs await to execute. 5. **Mixing async SQLAlchemy and sync.** Pick one for clarity. ## Practical guidance For most FastAPI apps in 2026: - **Sync def + sync SQLAlchemy**: simpler, works fine. Good for CRUD apps. - **Async def + async SQLAlchemy**: when you need concurrency or call multiple external services per request. - **Mixed**: async def for I/O-heavy endpoints, sync def for simple CRUD. Don't optimize prematurely. Start simple; switch to async if you measure a bottleneck. ## Takeaway async def runs in event loop; def runs in threadpool. Both work in FastAPI. Async benefits when you await multiple I/O operations (HTTP, DB, etc.). Sync is fine for simple CRUD and when using sync libraries. Don't mix async def with sync I/O — blocks event loop. For most apps, start sync; go async when measured. Async ecosystem: