Idempotency trong REST API: vì sao quan trọng và cách triển khai

Một thao tác idempotent là thao tác thực hiện nhiều lần cho cùng kết quả như một lần. Đây là khái niệm sống còn khi mạng không đáng tin và client hay retry.

Method nào idempotent?

• GET, PUT, DELETE: idempotent — gọi lại không đổi kết quả cuối
• POST: KHÔNG idempotent — gọi hai lần thường tạo hai tài nguyên

Vấn đề thực tế

Client gửi POST /payments tạo giao dịch. Mạng chập chờn, client không nhận được phản hồi và tự retry. Kết quả: khách bị trừ tiền hai lần. Đây chính là lúc cần idempotency key.

Idempotency key

Client sinh một khoá duy nhất (thường là UUID) và gửi qua header Idempotency-Key. Server lưu khoá này cùng kết quả lần đầu; nếu thấy khoá đã xử lý, trả lại kết quả cũ thay vì tạo mới.

POST /payments
Idempotency-Key: 9f1c-4b2a-...

# Lần 2 cùng key -> server trả lại phản hồi lần 1, KHÔNG trừ tiền lần nữa

Triển khai

1. Lưu (key → response) trong bảng/cache với thời hạn hợp lý
2. Dùng ràng buộc UNIQUE trên key để chống race condition khi hai request cùng đến
3. Phía client: sinh key một lần cho một ý định thao tác, tái dùng khi retry

👉 Dùng thử công cụ liên quan trên dev-hub: UUID Generator — chạy hoàn toàn trong trình duyệt, không gửi dữ liệu lên server.