Thiết Kế API taste

# Thiết Kế API taste
- Ưu tiên các URL hướng tài nguyên sử dụng danh từ và dùng các phương thức HTTP (HTTP verbs) để biểu thị hành động, không đưa các động từ kiểu RPC vào đường dẫn. Độ tin cậy: 0.95
- Đánh số phiên bản API ngay trong đường dẫn URL (`/v1/...`) và không đưa các thay đổi gây tương thích ngược (breaking changes) vào một phiên bản chính (major version) đang tồn tại. Độ tin cậy: 0.90
- Sử dụng danh từ số nhiều cho tên các tập hợp (`/users`, `/orders`) và chỉ lồng sâu tối đa một cấp khi tài nguyên con không có ý nghĩa nếu đứng độc lập. Độ tin cậy: 0.85
- Trả về dữ liệu JSON với tên trường viết theo quy tắc camelCase nhất quán và không bao giờ trộn lẫn kiểu snake_case trong cùng một API. Độ tin cậy: 0.85
- Sử dụng các mã trạng thái HTTP tiêu chuẩn: 201 khi tạo mới thành công, 204 khi xóa thành công không kèm nội dung trả về, 404 khi không tìm thấy tài nguyên, 409 khi xảy ra xung đột. Độ tin cậy: 0.90
- Đặt các tham số phân trang, sắp xếp và lọc vào tham số truy vấn (query params); trả về siêu dữ liệu phân trang trong một cấu trúc vỏ bọc ổn định (`data`, `nextCursor`). Độ tin cậy: 0.85
- Ưu tiên phân trang dựa trên con trỏ (cursor-based pagination) hơn là dùng độ lệch (offset) đối với bất kỳ danh sách nào có thể phình to. Độ tin cậy: 0.90
- Xác thực mọi phần thân yêu cầu (request body) bằng một lược đồ (zod, OpenAPI, JSON Schema) và từ chối các trường không xác định. Độ tin cậy: 0.90
- Định hình cấu trúc phản hồi lỗi giống hệt nhau ở mọi nơi: gồm `code`, `message` và trường tùy chọn `details`. Độ tin cậy: 0.90
- Ưu tiên sử dụng khóa bất biến (idempotency keys) trên các điểm cuối POST có tạo giao dịch tiền tệ, đơn hàng hoặc gây ra hiệu ứng phụ. Độ tin cậy: 0.85
- Sử dụng ETags hoặc tiêu đề `If-Match` cho các thao tác cập nhật đồng thời trên những tài nguyên có sự tranh chấp. Độ tin cậy: 0.75
- Viết tài liệu API bằng chuẩn OpenAPI 3 và sinh mã trình khách (clients) tự động từ bản hợp đồng đó, thay vì tự viết tay các bộ SDK. Độ tin cậy: 0.85
- Không bao giờ đặt thông tin bí mật (secrets) hoặc thông tin định danh cá nhân (PII) vào URL hay chuỗi truy vấn (query strings); hãy đặt chúng trong phần tiêu đề (headers) hoặc phần thân yêu cầu (body). Độ tin cậy: 0.95
- Ưu tiên cơ chế mở rộng tường minh (`?include=`) hơn là lúc nào cũng nhúng sẵn toàn bộ các thực thể liên quan vào phản hồi. Độ tin cậy: 0.80
- Giữ cho các điểm cuối ghi dữ liệu (write endpoints) nhỏ gọn: mỗi đường dẫn chỉ thực hiện một thao tác thay đổi rõ ràng thay vì gom đủ thứ cập nhật vào một chỗ. Độ tin cậy: 0.80
- Giới hạn tần suất gọi (rate-limit) theo khóa API hoặc theo người dùng và trả về tiêu đề `Retry-After` khi chạm ngưỡng giới hạn. Độ tin cậy: 0.85
- Ưu tiên định dạng dấu thời gian chuẩn ISO-8601 theo múi giờ UTC và không bao giờ tự chế ra các định dạng chuỗi ngày tháng tùy chỉnh. Độ tin cậy: 0.95