A production-ready FastAPI backend keeps request handlers fast, validates input with Pydantic models, and moves slow work (emails, scraping, report generation) into background jobs so the API always answers quickly. This guide shows a small, practical structure you can extend.
How should you structure a FastAPI project?
Keep routing, schemas, and business logic apart:
app/
main.py # app creation, routers
schemas.py # Pydantic models
services.py # business logic
jobs.py # background work
Step 1: validated endpoints with Pydantic
# app/schemas.py
from pydantic import BaseModel, EmailStr # pip install "pydantic[email]"
class ReportRequest(BaseModel):
email: EmailStr
mc_number: str
class JobStatus(BaseModel):
job_id: str
status: str
Pydantic rejects malformed input with a clear 422 response before your code runs.
Step 2: accept the request, queue the work
# app/main.py
import uuid
from fastapi import FastAPI, BackgroundTasks
from .schemas import ReportRequest, JobStatus
from .jobs import build_report, JOBS
app = FastAPI()
@app.post("/reports", response_model=JobStatus, status_code=202)
async def create_report(req: ReportRequest, tasks: BackgroundTasks):
job_id = uuid.uuid4().hex
JOBS[job_id] = "queued"
tasks.add_task(build_report, job_id, req)
return JobStatus(job_id=job_id, status="queued")
@app.get("/reports/{job_id}", response_model=JobStatus)
async def report_status(job_id: str):
return JobStatus(job_id=job_id, status=JOBS.get(job_id, "unknown"))
Returning 202 Accepted tells the client the work is queued, and the client polls the status endpoint.
# app/jobs.py
import time
JOBS: dict[str, str] = {}
def build_report(job_id: str, req) -> None:
JOBS[job_id] = "running"
try:
time.sleep(5) # replace with real work
JOBS[job_id] = "done"
except Exception:
JOBS[job_id] = "failed"
When is BackgroundTasks not enough?
BackgroundTasks runs inside the same process. If the server restarts, queued work is lost, and the in-memory JOBS dict is not shared between workers. For anything important, store job state in a database or Redis and use a real queue such as Celery, RQ, or Arq.
Production checklist
- Run with
uvicornorgunicorn -k uvicorn.workers.UvicornWorkerbehind a reverse proxy such as nginx. - Load secrets from environment variables, never from code.
- Add a
/healthendpoint for monitors. - Log request IDs and exceptions.
- Write tests with
TestClientfrom FastAPI.
FAQ
Is FastAPI async only? No. You can declare handlers with def and FastAPI runs them in a thread pool.
Should I use BackgroundTasks or Celery? Use BackgroundTasks for small, non-critical work; use a queue when jobs must survive restarts or retry.
How do I document the API? FastAPI generates OpenAPI docs automatically at /docs.
Where should job state live? In a database or Redis, so every worker sees the same state.
Written by Muhammad Afzal, Python developer at INDUS Web Agency.
Top comments (0)