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ệ.

40 phútTrung cấp
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=2Lọc, sắp xếp, phân trang, tùy chọn
Thân yêu cầu (body)JSONDữ liệu tạo mới, cập nhật
HeaderAuthorizationXác thực, ngôn ngữ, định dạng
Cookiephiên làm việcTrạ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
  1. Viết API lấy sản phẩm theo id.
  2. Thêm lọc theo khoảng giá bằng query.
  3. 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.