Trong quá trình xây dựng các dự án cá nhân hoặc startup ở giai đoạn đầu, việc thiết kế một hệ thống API tốt từ những ngày đầu tiên sẽ giúp tiết kiệm rất nhiều thời gian bảo trì và mở rộng sau này.
Bài viết này mình sẽ tổng hợp lại một checklist những nguyên tắc thiết kế RESTful API mà mình thường áp dụng, hướng tới sự đơn giản, bền vững và dễ đọc cho cả con người lẫn máy móc.
1. Sử dụng danh từ số nhiều cho Endpoint
Hãy giữ endpoint thống nhất bằng cách sử dụng danh từ số nhiều cho các resource thay vì động từ. Động từ đã được thể hiện qua các HTTP Methods (GET, POST, PUT, DELETE).
// ❌ Không nên
POST /create-user
GET /get-users
POST /update-user/123
// ✅ Nên dùng
POST /users
GET /users
PUT /users/123
2. Versioning ngay từ đầu
Đừng đợi đến lúc API bị break mới nghĩ đến versioning. Hãy đưa version vào URL (phổ biến nhất) hoặc Header.
https://api.domain.com/v1/usershttps://api.domain.com/v2/users
Việc đập đi xây lại ở v2 sẽ nhẹ nhàng hơn rất nhiều nếu bạn đã có v1 tách biệt từ trước, client cũ không bị ảnh hưởng.
3. Chuẩn hóa format Response
Hãy tạo một cấu trúc response chuẩn để frontend (hoặc mobile app) có thể xử lý lỗi một cách đồng nhất.
{
"status": "success",
"data": {
"id": 123,
"name": "Nguyễn Đức Anh"
},
"message": "User created successfully"
}
Kết luận
Một hệ thống API tốt giống như một bản thiết kế nhà vững chắc. Dù ngôi nhà lúc đầu có nhỏ, nhưng móng tốt sẽ giúp bạn dễ dàng xây thêm tầng sau này. Hy vọng checklist nhỏ này sẽ giúp ích cho dự án tiếp theo của bạn!
