⭐ Python Developer · Chặng 9Bài 2/6Bài học~75 phút

FastAPI đầu tiên: endpoint, path, query, Pydantic, /docs

Viết Web API đầu tiên bằng FastAPI: cài đặt, fastapi dev, path và query parameter, request body Pydantic, mã lỗi và /docs.

FastAPI đầu tiên: endpoint, path, query, Pydantic, /docs

Học xong bài này, bạn sẽ

  • Tạo ứng dụng FastAPI và chạy bằng fastapi dev
  • Nhận path, query parameter và body có kiểm tra bằng Pydantic
  • Dùng tài liệu tự sinh /docs để thử API

Nên học trước: HTTP và REST cho backend developer

Nội dung bài viết
  1. 1. Cài đặt và Hello World
  2. 2. API sổ ghi chú hoàn chỉnh
  3. 3. Pydantic model: khai báo và kiểm tra dữ liệu
  4. 4. Path parameter và query parameter
  5. 5. Lỗi và mã trạng thái
  6. 6. Tài liệu tự động /docs
  7. Tóm tắt
  8. Bài tập

FastAPI là framework xây Web API phổ biến bậc nhất của Python hiện nay. Bạn khai báo kiểu dữ liệu bằng type hint như đã học ở chặng 5, FastAPI tự kiểm tra dữ liệu vào, chuyển đổi dữ liệu ra, trả lỗi rõ ràng và sinh tài liệu tương tác. Bài này xây API "sổ ghi chú" đầu tiên, lưu trong bộ nhớ; hai bài sau sẽ thêm cơ sở dữ liệu và đăng nhập.

1. Cài đặt và Hello World

$ uv init --no-package so-ghi-chu && cd so-ghi-chu
$ uv add "fastapi[standard]"

Gói fastapi[standard] kèm sẵn máy chủ Uvicorn, lệnh fastapi và các thư viện hay dùng. Tạo main.py:

# (minh họa) main.py tối giản
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def trang_chu() -> dict[str, str]:
    return {"thong_diep": "Xin chào từ FastAPI"}
$ uv run fastapi dev main.py
 ⚡️ Starting FastAPI in development mode
 🌐 Server started at http://127.0.0.1:8000
    Documentation at http://127.0.0.1:8000/docs
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Application startup complete.

Mở http://127.0.0.1:8000 trong trình duyệt sẽ thấy {"thong_diep":"Xin chào từ FastAPI"}. @app.get("/") là decorator (chặng 5) đăng ký hàm xử lý cho GET /; giá trị trả về (dict, list, đối tượng Pydantic) được tự chuyển thành JSON. fastapi dev tự khởi động lại mỗi khi bạn lưu file; chạy thật dùng fastapi run.

2. API sổ ghi chú hoàn chỉnh

from datetime import datetime
from typing import Annotated

from fastapi import FastAPI, HTTPException, Query, status
from pydantic import BaseModel, Field

app = FastAPI(title="Sổ ghi chú", version="0.1.0")


class GhiChuTao(BaseModel):
    """Dữ liệu client gửi lên khi tạo ghi chú."""

    tieu_de: str = Field(min_length=1, max_length=100)
    noi_dung: str = ""
    the: list[str] = []


class GhiChu(GhiChuTao):
    """Dữ liệu API trả về: thêm id và thời điểm tạo."""

    id: int
    tao_luc: datetime


KHO: dict[int, GhiChu] = {}  # lưu trong bộ nhớ: mất khi tắt máy chủ (bài sau dùng CSDL)
id_ke_tiep = 1


@app.get("/")
def trang_chu() -> dict[str, str]:
    return {"thong_diep": "Xin chào từ FastAPI"}


@app.post("/ghi-chu", status_code=status.HTTP_201_CREATED)
def tao_ghi_chu(du_lieu: GhiChuTao) -> GhiChu:
    global id_ke_tiep
    gc = GhiChu(id=id_ke_tiep, tao_luc=datetime.now(), **du_lieu.model_dump())
    KHO[gc.id] = gc
    id_ke_tiep += 1
    return gc


@app.get("/ghi-chu")
def liet_ke(
    tu_khoa: str | None = None,
    skip: Annotated[int, Query(ge=0)] = 0,
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
) -> list[GhiChu]:
    ket_qua = list(KHO.values())
    if tu_khoa:
        k = tu_khoa.casefold()
        ket_qua = [g for g in ket_qua if k in g.tieu_de.casefold() or k in g.noi_dung.casefold()]
    return ket_qua[skip : skip + limit]


@app.get("/ghi-chu/{ghi_chu_id}")
def xem(ghi_chu_id: int) -> GhiChu:
    if ghi_chu_id not in KHO:
        raise HTTPException(status_code=404, detail="Không tìm thấy ghi chú")
    return KHO[ghi_chu_id]


@app.delete("/ghi-chu/{ghi_chu_id}", status_code=status.HTTP_204_NO_CONTENT)
def xoa(ghi_chu_id: int) -> None:
    if KHO.pop(ghi_chu_id, None) is None:
        raise HTTPException(status_code=404, detail="Không tìm thấy ghi chú")

Hơn 60 dòng, đủ 4 endpoint, kiểm tra dữ liệu và tài liệu tự động. Phần tiếp theo giải thích từng thành phần.

3. Pydantic model: khai báo và kiểm tra dữ liệu

GhiChuTao kế thừa BaseModel của Pydantic: khai báo trường bằng type hint, ràng buộc bằng Field. Khi endpoint có tham số kiểu model (du_lieu: GhiChuTao), FastAPI đọc body JSON, kiểm tra từng trường, chuyển kiểu, và chỉ gọi hàm của bạn khi dữ liệu hợp lệ. Gửi tiêu đề rỗng:

$ curl -s -X POST localhost:8000/ghi-chu -H "Content-Type: application/json" -d '{"tieu_de": ""}'
{"detail":[{"type":"string_too_short","loc":["body","tieu_de"],"msg":"String should have at least 1 character","input":"","ctx":{"min_length":1}}]}

Mã 422 kèm vị trí lỗi (body → tieu_de) và lý do, bạn không viết dòng kiểm tra nào. Tách hai model GhiChuTao (client gửi lên) và GhiChu (API trả về, có thêm id, tao_luc) là thói quen quan trọng: client không được tự đặt id. Kiểu trả về -> GhiChu khiến FastAPI kiểm tra và lọc dữ liệu ra theo đúng model: lỡ trả thừa trường bí mật (như mật khẩu đã băm ở bài sau) thì trường đó bị loại bỏ.

4. Path parameter và query parameter

$ curl -s localhost:8000/ghi-chu/abc
{"detail":[{"type":"int_parsing","loc":["path","ghi_chu_id"],"msg":"Input should be a valid integer, unable to parse string as an integer","input":"abc"}]}
$ curl -s "localhost:8000/ghi-chu?limit=500"
{"detail":[{"type":"less_than_equal","loc":["query","limit"],"msg":"Input should be less than or equal to 100","input":"500","ctx":{"le":100}}]}
$ curl -s "localhost:8000/ghi-chu?tu_khoa=sữa"
[{"tieu_de":"Mua sữa","noi_dung":"2 hộp không đường","the":["việc nhà"],"id":1,"tao_luc":"2026-10-29T16:35:24.215696"}]
  • Tham số có tên trùng với {ghi_chu_id} trong đường dẫn là path parameter; kiểu int làm FastAPI tự chuyển "42" thành 42 và từ chối "abc".
  • Tham số còn lại có kiểu đơn giản là query parameter; có giá trị mặc định thì không bắt buộc. str | None = None nghĩa là tùy chọn.
  • Annotated[int, Query(ge=0)] thêm ràng buộc: lớn hơn hoặc bằng 0. Giới hạn limit tối đa 100 bảo vệ máy chủ khỏi request đòi trả hàng triệu bản ghi.

5. Lỗi và mã trạng thái

raise HTTPException(status_code=404, detail="...") dừng xử lý và trả lỗi cho client, đúng mã trạng thái như đã thiết kế ở bài HTTP. status_code=status.HTTP_201_CREATED trong decorator đặt mã cho trường hợp thành công; status chứa sẵn hằng số cho mọi mã, đọc dễ hơn số trần. Endpoint xóa trả 204 không có body.

6. Tài liệu tự động /docs

Mở http://127.0.0.1:8000/docs: FastAPI sinh trang tài liệu Swagger UI từ code, liệt kê mọi endpoint, tham số, ràng buộc, model dữ liệu. Bấm Try it out để gửi request thật ngay trên trình duyệt. /redoc là một giao diện tài liệu khác; /openapi.json là bản mô tả OpenAPI dạng máy đọc được, dùng để sinh code client tự động. Tài liệu luôn khớp với code, vì nó được sinh từ code.

Dữ liệu trong bộ nhớ chỉ để họcBiến KHO mất sạch khi máy chủ khởi động lại (kể cả mỗi lần fastapi dev tự nạp lại khi bạn lưu file), và không dùng chung được khi chạy nhiều tiến trình. Bài sau thay bằng SQLite qua SQLAlchemy. global id_ke_tiep cũng chỉ chấp nhận được trong ví dụ này.

Tóm tắt

  • uv add "fastapi[standard]"; fastapi dev main.py khi phát triển, fastapi run khi chạy thật.
  • @app.get/post/patch/delete("/duong-dan/{id}"); giá trị trả về tự thành JSON.
  • Pydantic BaseModel + Field cho body; tách model tạo và model trả về; kiểu trả về lọc dữ liệu ra.
  • Path parameter theo tên trong đường dẫn, query parameter có mặc định, ràng buộc bằng Annotated[..., Query(...)].
  • HTTPException cho lỗi; /docs để thử API.

Bài tập

Bài 1. Chạy và thử API

Chạy API sổ ghi chú, dùng /docs tạo 3 ghi chú, liệt kê, xem ghi chú số 2, xóa ghi chú số 1, rồi xem lại số 1 (phải là 404). Thử gửi body thiếu tieu_de và đọc lỗi 422.

Xem gợi ý

Thiếu trường bắt buộc cho lỗi kiểu "type":"missing","loc":["body","tieu_de"]. Thử thêm "the": "abc" (chuỗi thay vì list) để thấy Pydantic báo list_type. Mỗi lần lưu main.py, máy chủ nạp lại và dữ liệu mất: đúng như cảnh báo ở mục 6.

Bài 2. Lọc theo thẻ

Thêm query parameter the cho endpoint liệt kê: chỉ trả ghi chú có thẻ đó. Kết hợp được với tu_khoa và phân trang.

Xem đáp án
# (minh họa) thay hàm liet_ke trong main.py
@app.get("/ghi-chu")
def liet_ke(
    tu_khoa: str | None = None,
    the: str | None = None,
    skip: Annotated[int, Query(ge=0)] = 0,
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
) -> list[GhiChu]:
    ket_qua = list(KHO.values())
    if tu_khoa:
        k = tu_khoa.casefold()
        ket_qua = [g for g in ket_qua if k in g.tieu_de.casefold() or k in g.noi_dung.casefold()]
    if the:
        ket_qua = [g for g in ket_qua if the in g.the]
    return ket_qua[skip : skip + limit]
$ curl -s "localhost:8000/ghi-chu?the=việc%20nhà" | python -m json.tool --no-ensure-ascii
[
    {
        "tieu_de": "Mua sữa",
        "noi_dung": "2 hộp không đường",
        "the": [
            "việc nhà"
        ],
        "id": 1,
        "tao_luc": "2026-10-29T16:35:24.215696"
    }
]

Thứ tự lọc rồi mới phân trang là quan trọng: phân trang trước sẽ làm mất kết quả khớp nằm ở trang sau. python -m json.tool --no-ensure-ascii định dạng JSON cho dễ đọc và giữ nguyên chữ có dấu. Ở bài sau, lọc sẽ do câu SQL làm thay vì duyệt list trong Python.

Nguồn tham khảo: FastAPI: First Steps; Request Body; Query Parameters and String Validations; Pydantic: Models.

Bài tập thực hành

  1. Viết API sổ ghi chú lưu trong bộ nhớ: tạo, liệt kê, xem, xóa ghi chú, trả 404 khi không tìm thấy.
  2. Thêm query parameter tu_khoa và phân trang skip, limit (tối đa 100) cho endpoint liệt kê.

Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.

Bài tiếp theo
Ban biên tập HocFree

Chúng tôi viết những bài hướng dẫn dễ hiểu, thực tế để ai cũng có thể tự học lập trình và AI, hoàn toàn miễn phí.