FastAPI Dynamic Router

FastAPI extension that provides automatic and dynamic route registration for FastAPI applications, inspired by Next.js's file-system based routing.

Installation

pip install fastapi-dynamic-router

How to Use

Basic Setup

from fastapi import FastAPI
from fastapi_dynamic_router import DynamicRouter

# Create FastAPI app
app = FastAPI()

# Initialize the router
router = DynamicRouter(app)

# Register routes from a directory
router.register_routes('routes')

if __name__ == '__main__':
    import uvicorn
    uvicorn.run(app)

Route Examples

1. Basic Route (routes/root/__init__.py):

from fastapi import APIRouter

router = APIRouter()

@router.get('/')
def index():
    return {'message': 'Welcome to the API'}

2. Dynamic Parameter (routes/users/[user_id]/__init__.py):

from fastapi import APIRouter

router = APIRouter()

@router.get('/')
def get_user(user_id: str):
    return {'message': f'User details for ID: {user_id}'}

3. Nested Routes (routes/products/[productID]/reviews/__init__.py):

from fastapi import APIRouter

router = APIRouter()

@router.get('/')
def get_reviews(product_id: str):
    return {'message': f'Reviews for product ID: {product_id}'}

Configuration Options

# Make routes case-insensitive
app.state.dynamic_router_config['case_sensitive'] = False

# Add a global prefix to all routes
app.state.dynamic_router_config['prefix'] = '/api/v1'

Using with AI coding agents (Claude Code, Codex, Cursor, ...)

File-system routing is easy for agents to follow, as long as they know the convention. Two things help:

1. Tell your agent how routing works. Append the ready-made instructions to your project's CLAUDE.md / AGENTS.md:

python -m fastapi_dynamic_router agents >> CLAUDE.md

The agent then adds endpoints by creating folders, and never wires include_router into main.py by hand.

2. Give it a route map. Instead of searching the codebase for the handler behind a URL, the agent reads one file:

router.register_routes('routes', route_map='ROUTES.md')  # rewritten on every startup

or generate it without starting the app:

python -m fastapi_dynamic_router map routes -o ROUTES.md

| Method | Path | Handler | File |
|---|---|---|---|
| GET | `/` | `root` | `routes/root/__init__.py:6` |
| GET | `/users/{user_id}/` | `get_user` | `routes/users/[user_id]/__init__.py:6` |

The same data is available in code via router.get_route_map().

Directory Structure

The router follows a convention-based approach where your directory structure maps directly to URL routes:

📦 routes
├── 📂 Root
│   ├── 📄 __init__.py          ➜  🌐 /
│   ├── 📂 version
│   │   └── 📄 __init__.py      ➜  🌐 /version
│   └── 📂 about
│       └── 📄 __init__.py      ➜  🌐 /about
│
├── 📂 users
│   ├── 📄 __init__.py          ➜  🌐 /users
│   ├── 📂 [userID]             ➜  💫 Dynamic Parameter
│   │   ├── 📄 __init__.py      ➜  🌐 /users/{user_id}
│   │   └── 📂 profile
│   │       └── 📄 __init__.py  ➜  🌐 /users/{user_id}/profile
│   └── 📂 settings
│       └── 📄 __init__.py      ➜  🌐 /users/settings
│
└── 📂 products
    ├── 📄 __init__.py          ➜  🌐 /products
    └── 📂 [productID]          ➜  💫 Dynamic Parameter
        └── 📄 __init__.py      ➜  🌐 /products/{product_id}

Route Mapping Examples

Dynamic Parameters

Dynamic parameters are defined using square brackets in directory names:

• 📂 [userID] ➜ {user_id}
• 📂 [productID] ➜ {product_id}
• 📂 [categoryName] ➜ {category_name}

License

This project is licensed under the MIT License - see the LICENSE file for details.