239 lines
4.8 KiB
Markdown
239 lines
4.8 KiB
Markdown
# FastAPI – Advanced Path and Query Parameters
|
||
|
||
This document demonstrates advanced usage of **path parameters** and **query parameters** in FastAPI, including:
|
||
|
||
* Validation rules
|
||
* Aliases
|
||
* Descriptions for OpenAPI
|
||
* Deprecation flags
|
||
* Clear separation of responsibilities between path and query parameters
|
||
|
||
---
|
||
|
||
## Example Application
|
||
|
||
Create or update `main.py` with the following content:
|
||
|
||
```python
|
||
from fastapi import FastAPI, Query, Path, status
|
||
from fastapi.responses import JSONResponse
|
||
|
||
app = FastAPI()
|
||
|
||
users_db = [
|
||
{"id": "1", "name": "radin"}
|
||
]
|
||
|
||
|
||
@app.get("/user/{target_id}")
|
||
def get_user_by_path(
|
||
target_id: int = Path(
|
||
...,
|
||
alias="User ID",
|
||
description="Enter target unique ID",
|
||
deprecated=True,
|
||
)
|
||
):
|
||
for item in users_db:
|
||
if int(item["id"]) == target_id:
|
||
return JSONResponse(
|
||
content={"msg": f"Your target user name is {item['name']}"},
|
||
status_code=status.HTTP_200_OK,
|
||
)
|
||
|
||
return JSONResponse(
|
||
content={"msg": "user not found"},
|
||
status_code=status.HTTP_404_NOT_FOUND,
|
||
)
|
||
|
||
|
||
@app.get("/user")
|
||
def get_user_by_query(
|
||
target: int | None = Query(
|
||
default=None,
|
||
gt=0,
|
||
alias="User ID",
|
||
description="Enter target unique ID",
|
||
)
|
||
):
|
||
for item in users_db:
|
||
if item["id"] == str(target):
|
||
return JSONResponse(
|
||
content={"msg": f"Your target user name is {item['name']}"},
|
||
status_code=status.HTTP_200_OK,
|
||
)
|
||
|
||
return JSONResponse(
|
||
content={"msg": "user not found"},
|
||
status_code=status.HTTP_404_NOT_FOUND,
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## Path Parameter Example
|
||
|
||
### Endpoint
|
||
|
||
```http
|
||
GET /user/{target_id}
|
||
```
|
||
|
||
**Example Request:**
|
||
|
||
```
|
||
/user/1
|
||
```
|
||
|
||
### Characteristics
|
||
|
||
* Always required
|
||
* Defined as part of the route
|
||
* Used to identify a specific resource
|
||
* Missing value results in **404 Not Found**
|
||
* Supports validation, aliases, and documentation metadata
|
||
|
||
---
|
||
|
||
## Query Parameter Example
|
||
|
||
### Endpoint
|
||
|
||
```http
|
||
GET /user?User%20ID=1
|
||
```
|
||
|
||
### Characteristics
|
||
|
||
* Optional by default
|
||
* Used for filtering and searching
|
||
* Not part of the route path
|
||
* Supports validation and documentation metadata
|
||
* Uses default values when not provided
|
||
|
||
---
|
||
|
||
## Advanced Parameter Configuration
|
||
|
||
### `Path()` Example
|
||
|
||
```python
|
||
Path(
|
||
...,
|
||
alias="User ID",
|
||
description="Enter target unique ID",
|
||
deprecated=True
|
||
)
|
||
```
|
||
|
||
* `...` → parameter is required
|
||
* `alias` → custom name in documentation and URL
|
||
* `description` → shown in Swagger UI
|
||
* `deprecated` → marked as deprecated in OpenAPI
|
||
|
||
---
|
||
|
||
### `Query()` Example
|
||
|
||
```python
|
||
Query(
|
||
default=None,
|
||
gt=0,
|
||
alias="User ID",
|
||
description="Enter target unique ID"
|
||
)
|
||
```
|
||
|
||
* `gt=0` → value must be greater than zero
|
||
* Optional parameter with validation rules
|
||
* Appears in API documentation
|
||
|
||
---
|
||
|
||
## Path vs Query Parameters
|
||
|
||
### 1. Path Parameters
|
||
|
||
**What they are**
|
||
Values embedded directly in the URL path that identify a specific resource.
|
||
|
||
**When to use**
|
||
When the parameter is mandatory and uniquely identifies a resource.
|
||
|
||
**Example URL**
|
||
|
||
```
|
||
/users/42
|
||
```
|
||
|
||
**FastAPI Example**
|
||
|
||
```python
|
||
@app.get("/users/{user_id}")
|
||
def get_user(user_id: int):
|
||
return {"user_id": user_id}
|
||
```
|
||
|
||
**Key Points**
|
||
|
||
* Always required
|
||
* Part of the route definition
|
||
* Used for IDs and unique identifiers
|
||
* Missing value → 404 error
|
||
|
||
---
|
||
|
||
### 2. Query Parameters
|
||
|
||
**What they are**
|
||
Key-value pairs appended to the URL after `?`.
|
||
|
||
**When to use**
|
||
For optional filtering, searching, sorting, and pagination.
|
||
|
||
**Example URL**
|
||
|
||
```
|
||
/users?limit=10&active=true
|
||
```
|
||
|
||
**FastAPI Example**
|
||
|
||
```python
|
||
@app.get("/users")
|
||
def list_users(limit: int = 10, active: bool = True):
|
||
return {"limit": limit, "active": active}
|
||
```
|
||
|
||
**Key Points**
|
||
|
||
* Optional by default
|
||
* Not part of the route path
|
||
* Used to modify or filter results
|
||
* Defaults are used when missing
|
||
|
||
---
|
||
|
||
## Side-by-Side Comparison
|
||
|
||
| Feature | Path Parameter | Query Parameter |
|
||
| ------------- | ------------------- | --------------------------------- |
|
||
| Location | Inside URL path | After `?` |
|
||
| Required | Yes | No (by default) |
|
||
| Purpose | Identify a resource | Filter or modify results |
|
||
| Example | `/items/5` | `/items?limit=10` |
|
||
| Missing Value | 404 Not Found | Default value or validation error |
|
||
|
||
---
|
||
|
||
## Best Practices
|
||
|
||
* Use path parameters for resource identification
|
||
* Use query parameters for filtering and modifiers
|
||
* Avoid spaces in parameter aliases for production APIs
|
||
* Deprecate parameters instead of removing them
|
||
* Use validation (`gt`, `lt`, `regex`) for safer APIs
|
||
* Keep URL design consistent across services
|
||
* Prefer response models over manual JSON responses when possible
|
||
|