APIRouter

Router class for organizing FastAPI path operations into modular components

The APIRouter class is used to group path operations together, typically for organizing an application into multiple files. It provides the same interface as FastAPI for defining routes but can be included in the main application or other routers.

Class Signature

from fastapi import APIRouter

router = APIRouter(
    prefix="",
    tags=None,
    dependencies=None,
    responses=None,
)

Constructor Parameters

prefix · str · default: ""

An optional path prefix for the router. Must start with / and not end with /.

router = APIRouter(prefix="/api/v1")

tags · list[str | Enum] | None · default: "None"

A list of tags to be applied to all path operations in this router. It will be added to the generated OpenAPI.

router = APIRouter(tags=["users", "authentication"])

dependencies · Sequence[Depends] | None · default: "None"

A list of dependencies to be applied to all path operations in this router.

from fastapi import Depends

router = APIRouter(
    dependencies=[Depends(verify_token), Depends(verify_key)]
)

default_response_class · type[Response] · default: "JSONResponse"

The default response class to be used for all path operations in this router.

from fastapi.responses import ORJSONResponse

router = APIRouter(default_response_class=ORJSONResponse)

responses · dict[int | str, dict[str, Any]] | None · default: "None"

Additional responses to be shown in OpenAPI for all path operations in this router.

router = APIRouter(
    responses={
        404: {"description": "Not found"},
        500: {"description": "Internal server error"},
    }
)

callbacks · list[BaseRoute] | None · default: "None"

OpenAPI callbacks that should apply to all path operations in this router.

redirect_slashes · bool · default: "True"

Whether to detect and redirect slashes in URLs when the client doesn’t use the same format.

deprecated · bool | None · default: "None"

Mark all path operations in this router as deprecated in the generated OpenAPI.

router = APIRouter(deprecated=True)

include_in_schema · bool · default: "True"

Whether to include all path operations in this router in the generated OpenAPI.

router = APIRouter(include_in_schema=False)

lifespan · Lifespan[Any] | None · default: "None"

A Lifespan context manager handler for startup and shutdown events.

route_class · type[APIRoute] · default: "APIRoute"

Custom route class to be used by this router.

generate_unique_id_function · Callable[[APIRoute], str] · default: "generate_unique_id"

Customize the function used to generate unique IDs for path operations.

strict_content_type · bool · default: "True"

Enable strict checking for request Content-Type headers.

Methods

Path Operation Decorators

@router.get(path, **kwargs)

Define a GET endpoint.

@router.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

@router.post(path, **kwargs)

Define a POST endpoint.

@router.post("/items/")
async def create_item(item: Item):
    return item

@router.put(path, **kwargs)

Define a PUT endpoint.

@router.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, **item.dict()}

@router.patch(path, **kwargs)

Define a PATCH endpoint.

@router.delete(path, **kwargs)

Define a DELETE endpoint.

@router.options(path, **kwargs)

Define an OPTIONS endpoint.

@router.head(path, **kwargs)

Define a HEAD endpoint.

@router.trace(path, **kwargs)

Define a TRACE endpoint.

All decorators accept the same parameters as FastAPI path operation decorators:

response_model · Any

Pydantic model for response validation.

status_code · int | None

Default status code for the response.

tags · list[str | Enum] | None

Tags for OpenAPI documentation.

dependencies · Sequence[Depends] | None

Additional dependencies for this specific route.

summary · str | None

Short summary for OpenAPI documentation.

description · str | None

Detailed description for OpenAPI documentation.

deprecated · bool | None

Mark this route as deprecated.

add_api_route()

add_api_route(path, endpoint, **kwargs)

Add an API route programmatically.

router.add_api_route(
    "/items/",
    read_items,
    methods=["GET"],
    tags=["items"],
)

Accepts the same parameters as the path operation decorators.

include_router()

include_router(router, *, prefix="", tags=None, dependencies=None, **kwargs)

Include another APIRouter in this router.

router · APIRouter · required

The APIRouter to include.

prefix · str · default: ""

URL path prefix for all routes in the included router.

tags · list[str | Enum] | None

Additional tags to be applied to all routes.

dependencies · Sequence[Depends] | None

Additional dependencies to be applied to all routes.

deprecated · bool | None

Mark all routes as deprecated.

include_in_schema · bool · default: "True"

Include routes in OpenAPI schema.

from fastapi import APIRouter

api_router = APIRouter()
users_router = APIRouter()

@users_router.get("/")
def read_users():
    return [{"name": "Rick"}, {"name": "Morty"}]

api_router.include_router(users_router, prefix="/users", tags=["users"])

add_api_websocket_route()

add_api_websocket_route(path, endpoint, name=None, *, dependencies=None)

Add a WebSocket route programmatically.

path · str · required

WebSocket path.

endpoint · Callable · required

WebSocket endpoint function.

name · str | None

Name for the WebSocket route.

dependencies · Sequence[Depends] | None

Dependencies for this WebSocket route.

router.add_api_websocket_route("/ws", websocket_endpoint)

websocket()

@router.websocket(path, name=None, *, dependencies=None)

Define a WebSocket endpoint.

from fastapi import APIRouter, WebSocket

router = APIRouter()

@router.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Message: {data}")

Attributes

prefix · str

The path prefix for this router.

tags · list[str | Enum]

Tags applied to all routes in this router.

dependencies · list[Depends]

Dependencies applied to all routes in this router.

routes · list[BaseRoute]

List of all routes registered in this router.

deprecated · bool | None

Whether all routes are marked as deprecated.

include_in_schema · bool

Whether routes are included in the OpenAPI schema.

Example: Organizing Routes

# app/routers/users.py
from fastapi import APIRouter, Depends
from ..dependencies import get_token_header

router = APIRouter(
    prefix="/users",
    tags=["users"],
    dependencies=[Depends(get_token_header)],
    responses={404: {"description": "Not found"}},
)

@router.get("/")
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]

@router.get("/me")
async def read_user_me():
    return {"username": "current_user"}

@router.get("/{username}")
async def read_user(username: str):
    return {"username": username}

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

router = APIRouter(
    prefix="/items",
    tags=["items"],
    responses={404: {"description": "Not found"}},
)

@router.get("/")
async def read_items():
    return [{"name": "Portal Gun"}, {"name": "Plumbus"}]

@router.get("/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id, "name": "Portal Gun"}

# app/main.py
from fastapi import FastAPI
from .routers import users, items

app = FastAPI()

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

@app.get("/")
async def root():
    return {"message": "Hello World"}

Example: Nested Routers

from fastapi import APIRouter, FastAPI

app = FastAPI()

# Main API router
api_router = APIRouter(prefix="/api/v1")

# Sub-routers
users_router = APIRouter(prefix="/users", tags=["users"])
items_router = APIRouter(prefix="/items", tags=["items"])

@users_router.get("/")
def get_users():
    return [{"username": "user1"}]

@items_router.get("/")
def get_items():
    return [{"name": "item1"}]

# Include sub-routers in main router
api_router.include_router(users_router)
api_router.include_router(items_router)

# Include main router in app
app.include_router(api_router)

# URLs will be:
# /api/v1/users/
# /api/v1/items/