DEV Community

Cover image for How Do You Build a Production-Ready FastAPI Backend with Background Jobs?
Muhammad Afzal Kalwar
Muhammad Afzal Kalwar

Posted on

How Do You Build a Production-Ready FastAPI Backend with Background Jobs?

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"))
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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 uvicorn or gunicorn -k uvicorn.workers.UvicornWorker behind a reverse proxy such as nginx.
  • Load secrets from environment variables, never from code.
  • Add a /health endpoint for monitors.
  • Log request IDs and exceptions.
  • Write tests with TestClient from 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)