Với sản phẩm nhỏ, backend API thường bắt đầu rất đơn giản: vài endpoint CRUD, authentication cơ bản và một database. Nhưng nếu thiết kế vội, API sẽ nhanh chóng trở nên khó hiểu, khó debug và khó mở rộng khi sản phẩm có thêm tính năng.
Một API gọn gàng không nhất thiết phải theo mọi best practice phức tạp. Điều quan trọng là naming nhất quán, contract rõ, lỗi dễ đọc và behavior có thể dự đoán được.
Bắt đầu từ resource, không bắt đầu từ màn hình
Một lỗi phổ biến là thiết kế API theo từng màn hình frontend. Cách này nhanh lúc đầu nhưng dễ trùng lặp logic. Thay vào đó, hãy xác định resource chính của hệ thống: user, project, task, invoice, post, comment… rồi thiết kế endpoint xoay quanh chúng.
GET /api/projects
POST /api/projects
GET /api/projects/:id
PATCH /api/projects/:id
DELETE /api/projects/:idĐặt tên endpoint nhất quán
Endpoint nên dùng danh từ số nhiều cho collection và HTTP method để thể hiện hành động. Tránh đặt endpoint kiểu /getProject, /createProject nếu có thể biểu đạt bằng REST convention rõ ràng hơn.
- Dùng
GETđể đọc dữ liệu. - Dùng
POSTđể tạo mới. - Dùng
PATCHđể cập nhật một phần. - Dùng
DELETEđể xóa hoặc soft-delete. - Giữ naming nhất quán giữa các resource.
Chuẩn hóa response
Frontend sẽ dễ làm việc hơn nếu response có format ổn định. Với API nhỏ, bạn có thể giữ response đơn giản, nhưng nên thống nhất cách trả dữ liệu và lỗi.
{
"data": { ... },
"meta": {
"requestId": "req_123"
}
}Thiết kế error format dễ debug
Error không nên chỉ trả về “Something went wrong”. Một error tốt cần có mã lỗi, thông điệp dễ hiểu và chi tiết field nếu lỗi validation.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Dữ liệu không hợp lệ",
"fields": {
"email": "Email không đúng định dạng"
}
}
}Validation là tuyến phòng thủ đầu tiên
Đừng tin dữ liệu từ client. Mọi input quan trọng cần được validate ở backend: kiểu dữ liệu, độ dài, required field, permission và business rule. Validation rõ ràng giúp giảm bug lan xuống database hoặc service phía sau.
- Validate request body và query params.
- Không expose field nội bộ ra response nếu không cần.
- Không cho client tự set các field nhạy cảm như role, ownerId, priceCalculated.
- Log lỗi server nhưng không trả stack trace cho người dùng cuối.
Pagination và filter nên có từ sớm
Ngay cả khi dữ liệu ban đầu ít, endpoint list vẫn nên hỗ trợ pagination. Nếu không, app có thể chậm dần khi dữ liệu tăng.
GET /api/projects?page=1&limit=20&status=activeResponse có thể kèm thông tin tổng quan:
{
"data": [],
"meta": {
"page": 1,
"limit": 20,
"total": 128
}
}Auth và permission phải rõ ở từng endpoint
Authentication trả lời câu hỏi “bạn là ai”, còn authorization trả lời câu hỏi “bạn có được làm việc này không”. Sản phẩm nhỏ vẫn cần phân biệt hai việc này để tránh lỗi bảo mật.
Versioning: đừng làm quá sớm nhưng nên có đường lui
Với API nội bộ cho một app duy nhất, bạn chưa cần versioning phức tạp. Nhưng nếu API phục vụ mobile app đã phát hành, thay đổi breaking change cần rất cẩn thận vì người dùng có thể chưa cập nhật app.
Kết luận
Backend API cho sản phẩm nhỏ nên ưu tiên sự rõ ràng và nhất quán. Chỉ cần resource hợp lý, response ổn định, error dễ debug, validation chặt và pagination từ sớm, team đã tránh được rất nhiều nợ kỹ thuật. Đừng thiết kế quá phức tạp, nhưng cũng đừng để “nhanh cho xong” biến API thành nơi khó bảo trì nhất của sản phẩm.
