Bạn nên thiết kế cấu trúc và đặt tên field trong JSON response của API như thế nào?

Hãy hướng tới cấu trúc dễ đoán, để lập trình viên phía client đoán được field tiếp theo mà không cần đọc tài liệu.

{
  "data": [
    { "id": "ord_123", "status": "paid", "total_cents": 4599, "created_at": "2026-10-19T08:30:00Z" }
  ],
  "next_cursor": "eyJpZCI6MTIzfQ"
}

Những quy tắc đáng áp dụng:

• Chọn một kiểu đặt tên, snake_case hoặc camelCase, và dùng thống nhất ở mọi nơi.
• Dùng danh từ số nhiều cho collection, và object trong list có cùng cấu trúc với object khi đọc đơn lẻ.
• Bọc list trong một object. Mảng trần không chừa chỗ để thêm paging hay metadata sau này mà không gây breaking change.
• Trả ngày theo ISO 8601 có time zone, id dạng string, và tiền theo đơn vị nhỏ nhất hoặc decimal string.
• Dùng boolean thật và enum dạng string, và quyết định một lần là giá trị chưa đặt sẽ là null hay vắng mặt.
• Không để lộ tên cột database hay id nội bộ mà bạn có thể muốn đổi sau này.

Sự nhất quán quan trọng hơn bất kỳ lựa chọn riêng lẻ nào.