Project Structure

FastAPI does not impose a folder layout. A single file is a fine place to start, but as endpoints pile up you will want to split them by feature. Based on the "Bigger Applications" example from the official docs, this chapter covers a common layout, routers, configuration files and conventions.

A recommended layout

hello-fastapi/
├── app/
│   ├── __init__.py
│   ├── main.py          # creates FastAPI(), registers routers
│   ├── dependencies.py  # shared dependencies
│   ├── config.py        # settings (pydantic-settings)
│   ├── models.py        # Pydantic and SQLModel models
│   └── routers/
│       ├── __init__.py
│       ├── items.py
│       └── users.py
├── tests/
│   └── test_items.py
├── .env                 # local environment variables (not committed)
├── pyproject.toml       # or requirements.txt
└── Dockerfile

The app folder is a Python package. Every folder gets an __init__.py so imports like from app.routers import items work. Run the dev server with fastapi dev app/main.py; the fastapi command works out the package structure from the file path and finds the app object for you.

Splitting routes with APIRouter

An APIRouter behaves like a small FastAPI app. Create one per feature and give it a shared path prefix and documentation tags in one place.

# app/routers/items.py
from fastapi import APIRouter, HTTPException

router = APIRouter(prefix="/items", tags=["items"])

fake_items = {"plumbus": {"name": "Plumbus"}, "gun": {"name": "Portal Gun"}}


@router.get("/")
def list_items():
    return fake_items


@router.get("/{item_id}")
def read_item(item_id: str):
    if item_id not in fake_items:
        raise HTTPException(status_code=404, detail="Item not found")
    return fake_items[item_id]

main.py then only creates the app and registers routers. The entry point stays short, and each feature's code lives in its own file.

# app/main.py
from fastapi import FastAPI

from app.routers import items, users

app = FastAPI(title="Hello FastAPI", version="0.1.0")

app.include_router(items.router)
app.include_router(users.router)


@app.get("/health")
def health():
    return {"status": "ok"}

include_router also accepts prefix, tags and dependencies, so you can mount the same router under /api/v1, or require authentication for an entire admin router.

A dependencies module

Dependencies shared by several routers belong in dependencies.py. Here is a simple check of a token in a request header:

# app/dependencies.py
from typing import Annotated

from fastapi import Header, HTTPException


async def verify_token(x_token: Annotated[str, Header()]):
    if x_token != "secret-token":
        raise HTTPException(status_code=400, detail="X-Token header invalid")