Checklist khi review thiết kế API

1. URL dùng danh từ số nhiều, không chứa động từ (/users không phải /getUsers)?
2. HTTP method có đúng ngữ nghĩa (GET đọc, POST tạo, PUT thay thế toàn bộ, PATCH sửa 1 phần, DELETE xoá) không?
3. Các thao tác cần idempotent (đặc biệt PUT, và POST có rủi ro bị retry) có được xử lý đúng (hoặc có idempotency key) không?
4. Status code trả về có đúng nhóm (4xx cho lỗi client, 5xx cho lỗi server) không? Đặc biệt: lỗi validate có đang bị trả nhầm thành 5xx không?
5. Phân biệt đúng 401 (chưa xác thực) và 403 (đã xác thực nhưng thiếu quyền) chưa?
6. Response lỗi có lộ thông tin nhạy cảm (stack trace, câu SQL...) không?
7. Format lỗi có nhất quán giữa các endpoint không (nên theo 1 chuẩn chung, ví dụ RFC 9457 Problem Details)?
8. Versioning API có được áp dụng nhất quán 1 chiến lược duy nhất không?
9. Endpoint trả danh sách có hỗ trợ phân trang không? Nếu dữ liệu lớn/thay đổi liên tục, có đang dùng offset-based (dễ bị lệch trang) thay vì cursor-based không?
10. Có tài liệu OpenAPI/Swagger đầy đủ, cập nhật đúng với API thực tế không?
11. Nếu nhiều team/consumer cùng dùng API, có đang thiết kế contract-first (để các bên làm song song) hay chỉ code-first (dễ trễ tài liệu)?
12. CORS có được cấu hình đúng origin cần thiết không, hay đang để * kèm credentials (cấu hình sai/không an toàn)?
13. Các endpoint nhạy cảm (đăng nhập, gửi OTP...) có rate limiting và trả 429 kèm Retry-After khi vượt giới hạn không?