Ngày 11/11/2026, nhóm Wagtail giải thích vì sao API v3 của Wagtail 8.1 xây trên Django Ninja thay vì Django REST Framework (DRF): Ninja sinh schema OpenAPI ngay từ type hint của Python, còn tính năng này ở DRF đã deprecated và phải nhờ gói ngoài drf-spectacular. Đổi lại, Wagtail phải tự lo xác thực và phân quyền — những thứ DRF làm sẵn tốt hơn.

Wagtail là CMS trên Django được nhiều tổ chức lớn dùng, và API là cửa ngõ để frontend, mobile và AI agent đọc — nay là ghi — nội dung. Quyết định này ảnh hưởng tới hàng nghìn dự án Wagtail, và gợi ý cho ai đang phân vân giữa hai framework.

API v3 trong Wagtail 8.1 có gì mới

Wagtail 8.1 lấp đầy khoảng trống còn lại của API v3: ghi dữ liệu cho TypedTableBlock, quan hệ inline lồng nhau và thao tác workflow như duyệt hay hủy bài. Schema cũng chi tiết hơn cho StreamField, ForeignKey, ManyToManyField, quan hệ generic và redirect. API v2 vẫn được hỗ trợ trong 8.1, bị deprecated từ 8.2 và gỡ hẳn ở Wagtail 9.0 — người dùng headless nên lên kế hoạch chuyển sang v3 từ bây giờ.

Vì sao chọn Django Ninja: schema là “công dân hạng nhất”

Lý do lớn nhất là schema OpenAPI: với Ninja, sinh schema là tính năng gốc, đi thẳng từ type hint. Ở DRF, sinh schema tích hợp đã deprecated, giải pháp thực tế là gói ngoài drf-spectacular. Với một API mà AI agent và công cụ sinh client/SDK đọc mỗi ngày, schema lệch khỏi code thật là lỗi nghiêm trọng — Wagtail muốn schema sinh ra từ chính code.

from ninja import NinjaAPI, Schema
api = NinjaAPI()
class PageOut(Schema):
    id: int
    title: str
@api.get("/pages", response=list[PageOut])
def list_pages(request):
    return [{"id": 1, "title": "Trang chủ"}]

Cái giá phải trả: DRF vẫn hơn ở đâu

Nhóm Wagtail thẳng thắn thừa nhận Ninja không thắng ở mọi mặt. Xác thực và phân quyền là điểm yếu nhất: mô hình class-based của DRF — IsAuthenticated, DjangoModelPermissions, introspection qua OPTIONS — khớp tự nhiên với PermissionPolicy của Wagtail, còn Ninja không có permission class gốc. Lọc, phân trang và versioning của DRF cũng trưởng thành hơn. Hệ quả: Wagtail tự xây cơ chế xác thực và quản lý API token cho v3, làm tăng diện tích bảo trì. Wagtail còn soi cả sức khỏe dự án: lượt tải DRF bằng khoảng 50% lượt tải Django, Ninja chỉ khoảng 5%.

Điều này có ý nghĩa gì với bạn

Nếu bạn bắt đầu API Django mới và coi trọng schema chuẩn, tài liệu tự sinh và client/SDK tạo từ server, Django Ninja là lựa chọn hợp thời — đúng lý do Wagtail đã chọn. Nếu dự án đang chạy tốt trên DRF, không có lý do gì để chuyển. Còn nếu bạn dùng Wagtail headless, hãy thử API v3 ngay trên 8.1. Bài học lớn nhất: chọn dependency dài hơi thì nhìn cả lượt tải và maintainer, không chỉ tính năng hôm nay.

Bài viết liên quan

Câu hỏi thường gặp

Wagtail 8.1 có bỏ hẳn API v2 không?

Chưa. API v2 vẫn được hỗ trợ trong 8.1, bị deprecated từ 8.2 và gỡ hẳn ở Wagtail 9.0 — nên bắt đầu thử v3 ngay từ 8.1.

Dự án Django đang dùng DRF có nên chuyển sang Django Ninja không?

Không nhất thiết. Nếu DRF đang chạy tốt, hãy ở lại: DRF được bảo trì tốt và mạnh về phân quyền, lọc, phân trang. Chỉ cân nhắc Ninja cho API mới.

API v3 của Wagtail khác gì so với API v2?

API v3 đọc-ghi đầy đủ (v2 chỉ đọc), thêm actions, revisions và tài nguyên sites, locales, snippets, schema, whoami. Lỗi trả theo chuẩn Problem Details — nhưng v3 không hỗ trợ ?fields= như v2.

💬 Tin này ảnh hưởng tới dự án của bạn thế nào? Chia sẻ góc nhìn của bạn trong phần bình luận — mình đọc hết và sẽ tổng hợp những ý hay nhất.

Nguồn tham khảo