HTTP API: phương thức, mã trạng thái và tính idempotent

🔌 API là hợp đồng quan sát được

Một HTTP API mô tả tài nguyên bằng URI, dùng phương thức để biểu đạt ý định và trả status code cùng representation. Tên endpoint đẹp không cứu được hợp đồng mơ hồ: client cần biết dữ liệu bắt buộc, lỗi có cấu trúc, quyền truy cập và hành vi khi gửi lại yêu cầu.

Phương thức và ý định

• GET: lấy representation; được định nghĩa là safe và idempotent.
• PUT: tạo hoặc thay thế trạng thái tại URI đã biết; idempotent theo ngữ nghĩa.
• DELETE: yêu cầu loại bỏ liên kết tài nguyên; idempotent dù lần sau có thể trả status khác.
• POST: gửi dữ liệu để xử lí theo semantics của resource; mặc định không idempotent.

Ví dụ retry thanh toán

Nếu client timeout sau POST, nó không biết server đã tạo giao dịch chưa. Gửi lại tùy tiện có thể tạo hai lần. Một thiết kế có thể dùng idempotency key duy nhất, lưu kết quả lần đầu và trả lại kết quả tương ứng cho retry cùng khóa.

Mã trạng thái là một phần hợp đồng

2xx báo xử lí thành công; 4xx chỉ vấn đề ở request hoặc quyền; 5xx cho biết server không hoàn thành. Không trả 200 cho mọi trường hợp rồi giấu lỗi trong chuỗi body, vì proxy, client và quan sát hệ thống mất tín hiệu chuẩn.

✍️ Luyện tập

Thiết kế API đặt vé: nêu URI, method, request schema, lỗi hết chỗ, cơ chế retry và điều kiện hai request được coi là cùng thao tác.