Modular Routing with FastAPI APIRouter and Prefixes

As your application grows, keeping every route in a single main.py file quickly becomes unmaintainable. A file that starts at 50 lines can reach 500 lines by the time you’ve added employees, departments, authentication, and payroll endpoints. FastAPI’s APIRouter class solves this by letting you define routes in separate, self-contained files and then plug them into your main application with a single line. This lesson shows you how to split, organise, and register routers cleanly.

Modular Router Architecture

Instead of a monolithic main.py, you organise routes by domain. The main app acts as a hub that imports and attaches these sub-routers:

Creating a Sub-Router

Create the routers folder

mkdir routers
touch routers/__init__.py

Create the employee router file

Create routers/employees.py:

# routers/employees.py
from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel

# 1. Create the APIRouter instance with a prefix and tag
router = APIRouter(
    prefix="/employees",
    tags=["Employees"]
)

class Employee(BaseModel):
    id: int
    name: str
    department: str

# Sample mock data
EMPLOYEES = [
    Employee(id=1, name="Alice", department="Engineering"),
    Employee(id=2, name="Bob", department="HR")
]

# 2. Use @router instead of @app
@router.get("/", response_model=list[Employee])
def list_employees():
    return EMPLOYEES

@router.get("/{emp_id}", response_model=Employee)
def get_employee(emp_id: int):
    for emp in EMPLOYEES:
        if emp.id == emp_id:
            return emp
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Employee not found"
    )

@router.post("/", response_model=Employee, status_code=status.HTTP_201_CREATED)
def create_employee(employee: Employee):
    EMPLOYEES.append(employee)
    return employee

# main.py
from fastapi import FastAPI
from routers import employees

app = FastAPI(title="Employee Management System")

# Register the sub-router
app.include_router(employees.router)

@app.get("/")
def home():
    return {"message": "Welcome to the Modular EMS API!"}

Run the server

uvicorn main:app --reload

FastAPI maps all employee routes automatically:

GET /employees/
GET /employees/{emp_id}
POST /employees/

Understanding APIRouter Parameters

Parameter	Description
`prefix="/employees"`	Prepends this path to every route in the file. `@router.get("/")` becomes `GET /employees/`.
`tags=["Employees"]`	Groups these routes under an “Employees” section in Swagger UI and ReDoc.
`dependencies=[...]`	Apply dependencies (e.g., authentication) to every route in the router at once.

The prefix means you write shorter routes in each file. @router.get("/") is the employee list, and @router.get("/{emp_id}") is the single employee — the /employees prefix is added automatically when you register the router.

Adding a Second Router

Create routers/departments.py:

# routers/departments.py
from fastapi import APIRouter
from pydantic import BaseModel

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

class Department(BaseModel):
    id: int
    name: str

DEPARTMENTS = [
    Department(id=1, name="Engineering"),
    Department(id=2, name="Product"),
]

@router.get("/", response_model=list[Department])
def list_departments():
    return DEPARTMENTS

@router.post("/", response_model=Department, status_code=201)
def create_department(department: Department):
    DEPARTMENTS.append(department)
    return department

# main.py
from fastapi import FastAPI
from routers import employees, departments

app = FastAPI(title="Employee Management System")

app.include_router(employees.router)
app.include_router(departments.router)

@app.get("/")
def home():
    return {"message": "Welcome!"}

Scalable Folder Layout

For a modular project, organise your folders like this:

my_project/
│
├── main.py                    # App entrypoint
├── routers/                   # APIRouter files
│   ├── __init__.py
│   ├── employees.py           # Employee route endpoints
│   ├── departments.py         # Department route endpoints
│   └── auth.py                # Authentication endpoints
├── models/                    # Pydantic schemas
│   ├── __init__.py
│   └── employee.py
└── requirements.txt

Adding a new resource is now just two steps: create routers/payroll.py and add app.include_router(payroll.router) to main.py. Every other file stays unchanged.

Router-Level Dependencies

Apply a dependency to every route in a router at once — for example, requiring authentication for all admin endpoints:

from fastapi import APIRouter, Depends
from auth import get_current_user  # your auth dependency

admin_router = APIRouter(
    prefix="/admin",
    tags=["Admin"],
    dependencies=[Depends(get_current_user)]  # applied to ALL routes in this router
)

@admin_router.get("/stats")
def get_system_stats():
    return {"active_employees": 42}

@admin_router.delete("/employees/{employee_id}")
def admin_delete_employee(employee_id: int):
    return {"deleted": employee_id}

Both /admin/stats and /admin/employees/{id} will require authentication without you having to add Depends(get_current_user) to each function individually.

`include_router` Options

You can override or extend router settings when registering:

app.include_router(
    employees.router,
    prefix="/api/v1",          # Override or add an additional prefix
    tags=["v1 - Employees"],   # Override the tags
    deprecated=True            # Mark all routes in this router as deprecated
)

This is useful for API versioning — you can include the same router twice under /api/v1 and /api/v2 with different prefixes.

SQL & Databases

Data Analysis

FastAPI

Frontend

Modular Routing with FastAPI APIRouter and Prefixes

Modular Router Architecture

Creating a Sub-Router

Understanding APIRouter Parameters

Adding a Second Router

Scalable Folder Layout

Router-Level Dependencies

`include_router` Options

​Modular Router Architecture

​Creating a Sub-Router

​Understanding APIRouter Parameters

​Adding a Second Router

​Scalable Folder Layout

​Router-Level Dependencies

​include_router Options

Modular Router Architecture

Creating a Sub-Router

Understanding APIRouter Parameters

Adding a Second Router

Scalable Folder Layout

Router-Level Dependencies

`include_router` Options