API nhận dữ liệu qua đường dẫn (/sinhvien/5) và chuỗi truy vấn (?lop=K66). FastAPI dùng type hints để tự chuyển kiểu và kiểm tra hợp lệ.
Bạn sẽ học được
- Path parameter
- Query parameter, giá trị mặc định
- Kiểm tra với Path, Query
- Enum cho giá trị cố định
Cơ sở lý thuyết
API nhận dữ liệu từ nhiều vị trí của yêu cầu HTTP:
| Vị trí | Ví dụ | Dùng cho |
|---|---|---|
| Đường dẫn (path) | /sinhvien/15 | Định danh tài nguyên |
| Chuỗi truy vấn (query) | ?lop=K66&trang=2 | Lọc, sắp xếp, phân trang, tùy chọn |
| Thân yêu cầu (body) | JSON | Dữ liệu tạo mới, cập nhật |
| Header | Authorization | Xác thực, ngôn ngữ, định dạng |
| Cookie | phiên làm việc | Trạng thái phía trình duyệt |
- FastAPI suy ra vị trí từ khai báo: tên có trong mẫu đường dẫn là path; kiểu đơn giản còn lại là query; model Pydantic là body.
- Phân tích và kiểm tra (parse, validate): chuỗi "15" trong URL được chuyển thành int; giá trị sai kiểu trả lỗi 422 Unprocessable Entity kèm mô tả chi tiết.
- Ràng buộc bằng Path(), Query() (gt, ge, max_length, pattern) là một dạng lập trình theo hợp đồng: điều kiện đầu vào được khai báo rõ ràng.
- Thứ tự route: route cụ thể (/sinhvien/moi-nhat) phải khai báo trước route có tham số (/sinhvien/{id}).
Ví dụ
from enum import Enum
from typing import Annotated
from fastapi import FastAPI, Path, Query, HTTPException
app = FastAPI()
DS = {1: {"ten": "Lan", "lop": "K66"}, 2: {"ten": "Minh", "lop": "K67"}}
class XepLoai(str, Enum):
gioi = "gioi"
kha = "kha"
@app.get("/sinhvien/{sv_id}")
def lay_sv(sv_id: Annotated[int, Path(gt=0)]):
if sv_id not in DS:
raise HTTPException(status_code=404, detail="Không tìm thấy")
return DS[sv_id]
@app.get("/sinhvien")
def ds_sv(lop: str | None = None, trang: Annotated[int, Query(ge=1)] = 1):
kq = [sv for sv in DS.values() if lop is None or sv["lop"] == lop]
return {"trang": trang, "du_lieu": kq}
@app.get("/xep-loai/{loai}")
def theo_loai(loai: XepLoai):
return {"loai": loai}Gọi /sinhvien/abc sẽ tự nhận lỗi 422 vì sv_id phải là số nguyên.
Ứng dụng thực tế
Bài toán: API tìm kiếm sách thư viện: lọc theo từ khóa, năm xuất bản trong khoảng, nhiều thể loại, phân trang có giới hạn để tránh người dùng yêu cầu 1 triệu bản ghi một lần:
from typing import Annotated
from fastapi import Query
@app.get("/sach")
def tim_sach(
q: Annotated[str | None, Query(min_length=2, max_length=50)] = None,
tu_nam: Annotated[int, Query(ge=1900)] = 1900,
den_nam: Annotated[int, Query(le=2100)] = 2100,
the_loai: Annotated[list[str], Query()] = [], # ?the_loai=CNTT&the_loai=Toán
trang: Annotated[int, Query(ge=1)] = 1,
so_dong: Annotated[int, Query(ge=1, le=100)] = 20,
):
return {"dieu_kien": locals()}Thực hành
- Viết API lấy sản phẩm theo id.
- Thêm lọc theo khoảng giá bằng query.
- Trả 404 khi không tìm thấy.
Tóm tắt bài học
- {tên} trong đường dẫn là path parameter.
- Tham số khác là query parameter.
- Type hints tự kiểm tra và báo lỗi 422.

