API bền vững: pagination, idempotency, versioning và rate limit

API tốt là contract lâu dài#

API không chỉ là nơi frontend gọi dữ liệu. Nó là contract giữa các hệ thống. Một API bền vững cần predictable, dễ debug, kiểm soát lỗi tốt và có chiến lược thay đổi mà không phá client cũ. Các chủ đề quan trọng gồm pagination, idempotency, versioning, rate limit và error format.

Pagination tránh response quá lớn#

Endpoint listing không nên trả toàn bộ dữ liệu. Offset pagination dễ hiểu nhưng kém ổn định khi dữ liệu thay đổi liên tục và có thể chậm ở offset lớn. Cursor pagination thường tốt hơn cho feed hoặc danh sách lớn vì cursor dựa trên vị trí dữ liệu như id hoặc timestamp.

GET /api/posts?limit=20&cursor=2026-04-25T08:00:00Z

Dù dùng kiểu nào, hãy đặt giới hạn tối đa cho limit. Nếu client gửi limit=100000, server không nên tin. Giới hạn này vừa bảo vệ database vừa bảo vệ chi phí truyền tải.

Idempotency cho mutation nhạy cảm#

Idempotency nghĩa là retry cùng một thao tác không tạo thêm side effect không mong muốn. Với payment, order creation, email sending hoặc webhook processing, idempotency rất quan trọng vì network có thể timeout sau khi server đã xử lý thành công.

Một cách làm phổ biến là client gửi Idempotency-Key. Server lưu key, request hash và kết quả. Nếu nhận lại key đó, server trả kết quả cũ thay vì tạo resource mới.

POST /api/orders
Idempotency-Key: 7a2f4e7f-7c2f-4e2f-8c2d-72d2a6c9a111

Key cần có TTL và scope rõ, ví dụ theo user hoặc endpoint. Không nên dùng cùng một key cho nhiều loại mutation khác nhau.

Versioning và tương thích ngược#

API công khai hoặc có nhiều client cần chiến lược version. Version có thể nằm trong path như /v1, header hoặc media type. Quan trọng hơn vị trí version là nguyên tắc thay đổi: thêm field thường an toàn; xóa field, đổi kiểu dữ liệu hoặc đổi ý nghĩa status code là breaking change.

Khi cần thay đổi lớn, hãy deprecate có thời hạn, ghi log client còn dùng version cũ và cung cấp migration guide. Đừng phá client bằng một deploy bất ngờ.

Error format nên nhất quán#

Client cần biết lỗi là validation, auth, permission, conflict, rate limit hay server error. Hãy dùng HTTP status code đúng và body có cấu trúc ổn định.

{
  "error": {
    "code": "validation_failed",
    "message": "Title is required.",
    "fields": {
      "title": "Required"
    }
  }
}

Error message public không nên lộ stack trace, query SQL hoặc secret. Log nội bộ có thể chi tiết hơn, nhưng response public cần an toàn.

Rate limit là phần của contract#

Rate limit giúp bảo vệ API khỏi abuse và giữ chất lượng service cho người dùng thật. Endpoint login, search, comment, contact, upload và AI generation cần quan tâm đặc biệt. Khi rate limit, hãy trả status 429 và nếu phù hợp, thêm header cho biết khi nào client có thể thử lại.

Checklist API bền vững#

• Listing endpoint có pagination và max limit.
• Mutation rủi ro có idempotency key hoặc cơ chế chống duplicate.
• Status code đúng ý nghĩa và error body nhất quán.
• Breaking change có versioning, deprecation và migration plan.
• Rate limit bảo vệ endpoint dễ abuse.
• Response public không lộ field nhạy cảm.
• Log có request id, user id khi hợp lệ, status và latency.

Nguồn tham khảo chính#

• MDN: HTTP response status codes
• OWASP API Security Top 10 2023
• MDN: Retry-After header