pypi-fastapi

1
# API Routing
2

3
APIRouter allows organizing and grouping related API endpoints with shared configuration, middleware, and dependencies. Routers enable modular API design and can be included in the main FastAPI application or nested within other routers.
4

5
## Capabilities
6

7
### APIRouter Class
8

9
Router for organizing related endpoints with shared configuration including URL prefixes, tags, dependencies, and response models.
10

11
```python { .api }
12
class APIRouter:
13
    def __init__(
14
        self,
15
        *,
16
        prefix: str = "",
17
        tags: List[str] = None,
18
        dependencies: List[Depends] = None,
19
        default_response_class: Type[Response] = Default(JSONResponse),
20
        responses: dict = None,
21
        callbacks: List[BaseRoute] = None,
22
        routes: List[BaseRoute] = None,
23
        redirect_slashes: bool = True,
24
        default: ASGIApp = None,
25
        dependency_overrides_provider: Any = None,
26
        route_class: Type[APIRoute] = APIRoute,
27
        on_startup: List[Callable] = None,
28
        on_shutdown: List[Callable] = None,
29
        lifespan: Lifespan = None,
30
        deprecated: bool = None,
31
        include_in_schema: bool = True,
32
        generate_unique_id_function: Callable[[APIRoute], str] = Default(generate_unique_id),
33
        **kwargs: Any,
34
    ) -> None:
35
        """
36
        Create an APIRouter instance.
37

38
        Parameters:
39
        - prefix: Common URL prefix for all routes in this router
40
        - tags: List of tags for grouping routes in documentation
41
        - dependencies: List of dependencies applied to all routes
42
        - default_response_class: Default response class for all routes
43
        - responses: Additional response models for all routes
44
        - callbacks: List of callback routes
45
        - routes: List of routes to include in the router
46
        - deprecated: Mark all routes as deprecated
47
        - include_in_schema: Include router routes in OpenAPI schema
48
        """
49
```
50

51
### HTTP Method Decorators
52

53
Decorators for defining API endpoints on the router with the same functionality as FastAPI application decorators.
54

55
```python { .api }
56
def get(
57
    self,
58
    path: str,
59
    *,
60
    response_model: Any = Default(None),
61
    status_code: int = None,
62
    tags: List[str] = None,
63
    dependencies: List[Depends] = None,
64
    summary: str = None,
65
    description: str = None,
66
    response_description: str = "Successful Response",
67
    responses: dict = None,
68
    deprecated: bool = None,
69
    operation_id: str = None,
70
    response_model_include: IncEx = None,
71
    response_model_exclude: IncEx = None,
72
    response_model_by_alias: bool = True,
73
    response_model_exclude_unset: bool = False,
74
    response_model_exclude_defaults: bool = False,
75
    response_model_exclude_none: bool = False,
76
    include_in_schema: bool = True,
77
    response_class: Type[Response] = Default(JSONResponse),
78
    name: str = None,
79
    callbacks: List[BaseRoute] = None,
80
    openapi_extra: dict = None,
81
    generate_unique_id_function: Callable[[APIRoute], str] = Default(generate_unique_id),
82
) -> Callable[[DecoratedCallable], DecoratedCallable]:
83
    """
84
    Decorator for GET endpoints on this router.
85

86
    Parameters same as FastAPI.get() decorator.
87
    """
88

89
def post(self, path: str, **kwargs) -> Callable[[DecoratedCallable], DecoratedCallable]:
90
    """Decorator for POST endpoints on this router."""
91

92
def put(self, path: str, **kwargs) -> Callable[[DecoratedCallable], DecoratedCallable]:
93
    """Decorator for PUT endpoints on this router."""
94

95
def delete(self, path: str, **kwargs) -> Callable[[DecoratedCallable], DecoratedCallable]:
96
    """Decorator for DELETE endpoints on this router."""
97

98
def patch(self, path: str, **kwargs) -> Callable[[DecoratedCallable], DecoratedCallable]:
99
    """Decorator for PATCH endpoints on this router."""
100

101
def head(self, path: str, **kwargs) -> Callable[[DecoratedCallable], DecoratedCallable]:
102
    """Decorator for HEAD endpoints on this router."""
103

104
def options(self, path: str, **kwargs) -> Callable[[DecoratedCallable], DecoratedCallable]:
105
    """Decorator for OPTIONS endpoints on this router."""
106

107
def trace(self, path: str, **kwargs) -> Callable[[DecoratedCallable], DecoratedCallable]:
108
    """Decorator for TRACE endpoints on this router."""
109

110
def websocket(
111
    self,
112
    path: str,
113
    *,
114
    name: str = None,
115
    dependencies: List[Depends] = None,
116
) -> Callable[[DecoratedCallable], DecoratedCallable]:
117
    """Decorator for WebSocket endpoints on this router."""
118
```
119

120
### Router Composition
121

122
Methods for including sub-routers and adding routes programmatically to create hierarchical API structures.
123

124
```python { .api }
125
def include_router(
126
    self,
127
    router: APIRouter,
128
    *,
129
    prefix: str = "",
130
    tags: List[str] = None,
131
    dependencies: List[Depends] = None,
132
    default_response_class: Type[Response] = Default(JSONResponse),
133
    responses: dict = None,
134
    callbacks: List[BaseRoute] = None,
135
    deprecated: bool = None,
136
    include_in_schema: bool = True,
137
    generate_unique_id_function: Callable[[APIRoute], str] = Default(generate_unique_id),
138
) -> None:
139
    """
140
    Include another APIRouter in this router.
141

142
    Parameters:
143
    - router: APIRouter instance to include
144
    - prefix: Additional URL prefix for the included router
145
    - tags: Additional tags for all routes in the included router
146
    - dependencies: Additional dependencies for all routes
147
    - responses: Additional response models
148
    - deprecated: Mark all included routes as deprecated
149
    - include_in_schema: Include routes in OpenAPI schema
150
    """
151

152
def add_api_route(
153
    self,
154
    path: str,
155
    endpoint: Callable,
156
    *,
157
    methods: List[str] = None,
158
    name: str = None,
159
    response_model: Any = Default(None),
160
    status_code: int = None,
161
    tags: List[str] = None,
162
    dependencies: List[Depends] = None,
163
    summary: str = None,
164
    description: str = None,
165
    response_description: str = "Successful Response",
166
    responses: dict = None,
167
    deprecated: bool = None,
168
    operation_id: str = None,
169
    response_model_include: IncEx = None,
170
    response_model_exclude: IncEx = None,
171
    response_model_by_alias: bool = True,
172
    response_model_exclude_unset: bool = False,
173
    response_model_exclude_defaults: bool = False,
174
    response_model_exclude_none: bool = False,
175
    include_in_schema: bool = True,
176
    response_class: Type[Response] = Default(JSONResponse),
177
    callbacks: List[BaseRoute] = None,
178
    openapi_extra: dict = None,
179
    generate_unique_id_function: Callable[[APIRoute], str] = Default(generate_unique_id),
180
) -> None:
181
    """
182
    Add an API route programmatically to this router.
183

184
    Parameters same as FastAPI.add_api_route() method.
185
    """
186

187
def add_api_websocket_route(
188
    self,
189
    path: str,
190
    endpoint: Callable,
191
    *,
192
    name: str = None,
193
    dependencies: List[Depends] = None,
194
) -> None:
195
    """
196
    Add a WebSocket route programmatically to this router.
197

198
    Parameters same as FastAPI.add_api_websocket_route() method.
199
    """
200
```
201

202
### Route Mounting
203

204
Method for mounting ASGI applications and static file servers.
205

206
```python { .api }
207
def mount(
208
    self,
209
    path: str,
210
    app: ASGIApp,
211
    *,
212
    name: str = None,
213
) -> None:
214
    """
215
    Mount an ASGI application at the given path.
216

217
    Parameters:
218
    - path: URL path where the application should be mounted
219
    - app: ASGI application to mount
220
    - name: Name for the mount (for URL generation)
221
    """
222
```
223

224
### Route Classes
225

226
Individual route representation classes used internally by APIRouter.
227

228
```python { .api }
229
class APIRoute:
230
    """
231
    Individual API route representation with all route metadata,
232
    path parameters, dependencies, and response models.
233
    """
234
    def __init__(
235
        self,
236
        path: str,
237
        endpoint: Callable,
238
        *,
239
        response_model: Any = Default(None),
240
        status_code: int = None,
241
        tags: List[str] = None,
242
        dependencies: List[Depends] = None,
243
        summary: str = None,
244
        description: str = None,
245
        response_description: str = "Successful Response",
246
        responses: dict = None,
247
        deprecated: bool = None,
248
        name: str = None,
249
        methods: List[str] = None,
250
        operation_id: str = None,
251
        response_model_include: IncEx = None,
252
        response_model_exclude: IncEx = None,
253
        response_model_by_alias: bool = True,
254
        response_model_exclude_unset: bool = False,
255
        response_model_exclude_defaults: bool = False,
256
        response_model_exclude_none: bool = False,
257
        include_in_schema: bool = True,
258
        response_class: Type[Response] = Default(JSONResponse),
259
        callbacks: List[BaseRoute] = None,
260
        generate_unique_id_function: Callable[[APIRoute], str] = Default(generate_unique_id),
261
        openapi_extra: dict = None,
262
    ) -> None: ...
263

264
class APIWebSocketRoute:
265
    """
266
    WebSocket route representation for real-time communication endpoints.
267
    """
268
    def __init__(
269
        self,
270
        path: str,
271
        endpoint: Callable,
272
        *,
273
        name: str = None,
274
        dependencies: List[Depends] = None,
275
    ) -> None: ...
276
```
277

278
## Usage Examples
279

280
### Basic Router Usage
281

282
```python
283
from fastapi import APIRouter, FastAPI
284

285
# Create router for user-related endpoints
286
users_router = APIRouter(
287
    prefix="/users",
288
    tags=["users"],
289
    responses={404: {"description": "Not found"}}
290
)
291

292
@users_router.get("/")
293
def get_users():
294
    return [{"username": "john"}, {"username": "jane"}]
295

296
@users_router.get("/{user_id}")
297
def get_user(user_id: int):
298
    return {"user_id": user_id, "username": "john"}
299

300
@users_router.post("/")
301
def create_user(user: dict):
302
    return {"message": "User created", "user": user}
303

304
# Include router in main application
305
app = FastAPI()
306
app.include_router(users_router)
307
```
308

309
### Router with Dependencies
310

311
```python
312
from fastapi import APIRouter, Depends, HTTPException
313

314
def get_current_user():
315
    # Authentication logic here
316
    return {"username": "current_user"}
317

318
def admin_required(current_user: dict = Depends(get_current_user)):
319
    if not current_user.get("is_admin"):
320
        raise HTTPException(status_code=403, detail="Admin access required")
321
    return current_user
322

323
# Router with shared dependencies
324
admin_router = APIRouter(
325
    prefix="/admin",
326
    tags=["admin"],
327
    dependencies=[Depends(admin_required)]
328
)
329

330
@admin_router.get("/users")
331
def list_all_users():
332
    return {"users": ["admin", "user1", "user2"]}
333

334
@admin_router.delete("/users/{user_id}")
335
def delete_user(user_id: int):
336
    return {"message": f"User {user_id} deleted"}
337
```
338

339
### Nested Routers
340

341
```python
342
from fastapi import APIRouter, FastAPI
343

344
# Create nested router structure
345
api_v1_router = APIRouter(prefix="/api/v1")
346

347
users_router = APIRouter(prefix="/users", tags=["users"])
348
posts_router = APIRouter(prefix="/posts", tags=["posts"])
349

350
@users_router.get("/")
351
def get_users():
352
    return {"users": []}
353

354
@posts_router.get("/")
355
def get_posts():
356
    return {"posts": []}
357

358
# Include sub-routers in API v1 router
359
api_v1_router.include_router(users_router)
360
api_v1_router.include_router(posts_router)
361

362
# Include API v1 router in main application
363
app = FastAPI()
364
app.include_router(api_v1_router)
365

366
# This creates endpoints:
367
# GET /api/v1/users/
368
# GET /api/v1/posts/
369
```
370

371
### Router with Custom Response Models
372

373
```python
374
from fastapi import APIRouter
375
from pydantic import BaseModel
376
from typing import List
377

378
class User(BaseModel):
379
    id: int
380
    username: str
381
    email: str
382

383
class UserCreate(BaseModel):
384
    username: str
385
    email: str
386

387
# Router with default response class
388
users_router = APIRouter(
389
    prefix="/users",
390
    tags=["users"],
391
    responses={
392
        404: {"description": "User not found"},
393
        422: {"description": "Validation error"}
394
    }
395
)
396

397
@users_router.get("/", response_model=List[User])
398
def get_users():
399
    return [
400
        {"id": 1, "username": "john", "email": "john@example.com"},
401
        {"id": 2, "username": "jane", "email": "jane@example.com"}
402
    ]
403

404
@users_router.post("/", response_model=User, status_code=201)
405
def create_user(user: UserCreate):
406
    return {"id": 3, **user.dict()}
407
```