API Design Best Practices
Pagination/filtering/sorting nhất quán, chuẩn hoá lỗi bằng RFC 7807, idempotency key cho thao tác tiền bạc, và chiến lược versioning.
Đây là những chi tiết "nhỏ" quyết định API của bạn dễ dùng hay là nỗi ám ảnh của mọi client tích hợp vào nó. Một API thiếu pagination sẽ sập khi bảng dữ liệu đủ lớn; thiếu idempotency key sẽ tính tiền khách hàng 2 lần khi mạng chập chờn và client retry; format lỗi không nhất quán buộc mỗi client phải viết code xử lý lỗi riêng cho từng endpoint. Đây là những bài học thường phải trả giá bằng sự cố thật mới rút ra được.
🎯 Mục tiêu học tập
- Triển khai đúng cursor-based và offset-based pagination, biết khi nào dùng loại nào
- Chuẩn hoá format lỗi nhất quán trên toàn bộ API theo chuẩn RFC 7807
- Thiết kế idempotency key để bảo vệ các thao tác quan trọng (thanh toán, tạo đơn) khỏi retry trùng lặp
- Chọn chiến lược versioning phù hợp và biết đánh đổi của từng cách
Pagination — offset vs cursor
| Offset-based | Cursor-based | |
|---|---|---|
| Cú pháp | ?page=3&limit=20 | ?after=eyJpZCI6NDJ9&limit=20 |
| Nhảy tới trang bất kỳ | Có (trang 50 dễ dàng) | Không (chỉ next/prev tuần tự) |
| Hiệu năng với bảng lớn | Chậm dần — OFFSET 1000000 vẫn phải quét qua 1 triệu dòng | Nhanh, ổn định — dùng index trực tiếp (WHERE id > cursor) |
| Dữ liệu bị chèn/xoá khi đang phân trang | Có thể bị trùng/thiếu dòng (dữ liệu "trôi") | Ổn định, không bị ảnh hưởng |
Nguyên tắc: dùng offset cho UI cần hiển thị số trang cụ thể trên tập dữ liệu nhỏ/vừa; dùng cursor cho API công khai, infinite scroll, hoặc bảng dữ liệu lớn liên tục thay đổi (liên hệ trực tiếp kiến thức indexing ở khoá Database Engineering).
Chuẩn hoá lỗi — RFC 7807 Problem Details
Thay vì mỗi team/endpoint tự bịa format lỗi riêng, RFC 7807 định nghĩa 1 cấu trúc chung:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
{
"type": "https://api.example.com/errors/insufficient-stock",
"title": "Không đủ tồn kho",
"status": 422,
"detail": "Sản phẩm SKU-123 chỉ còn 2 trong kho, không đủ cho số lượng yêu cầu (5).",
"instance": "/orders/789"
}
Lợi ích: mọi client chỉ cần viết 1 lớp xử lý lỗi chung dựa trên cấu trúc cố định này thay vì đoán format
riêng của từng endpoint, và type là 1 URL định danh loại lỗi mà client có thể dùng để xử lý
logic riêng (ví dụ hiển thị thông báo khác nhau) mà không cần parse chuỗi title (vốn có thể
đổi ngôn ngữ hiển thị).
Idempotency Key — bảo vệ thao tác quan trọng khỏi retry trùng lặp
POST không idempotent theo mặc định — client retry (do timeout, mất mạng) 1 request tạo đơn hàng/thanh toán có thể vô tình tạo ra 2 bản ghi trùng nhau. Giải pháp chuẩn (dùng bởi Stripe và nhiều API thanh toán lớn): client gửi kèm 1 Idempotency-Key duy nhất cho mỗi thao tác logic (thường là UUID sinh ở client), server lưu lại kết quả gắn với key đó — nếu nhận lại cùng key, trả về đúng kết quả đã lưu từ lần đầu thay vì thực hiện lại thao tác.
POST /payments
Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
{ "amount": 500000, "currency": "VND" }
-- Server logic (giản lược):
-- 1. Tra bảng idempotency_keys theo key này
-- 2. Nếu đã tồn tại và đã xử lý xong -> trả về response đã lưu, KHÔNG chạy lại logic thanh toán
-- 3. Nếu chưa tồn tại -> khoá key này (tránh 2 request đồng thời cùng key chạy song song), xử lý, lưu kết quả
Đây là ứng dụng trực tiếp của transaction và locking đã học ở khoá Database Engineering — bảng
idempotency_keys cần unique constraint trên key và xử lý đúng concurrency khi 2 request trùng
key đến gần như đồng thời.
Versioning — 3 chiến lược phổ biến
| Chiến lược | Ví dụ | Ưu / nhược điểm |
|---|---|---|
| URI versioning | /v1/orders, /v2/orders | Rõ ràng, dễ debug, dễ route ở gateway — phổ biến nhất trong thực tế dù "không thuần REST" về mặt lý thuyết (URL nên đại diện resource, không đại diện version) |
| Header versioning | Accept: application/vnd.api+json;version=2 | URL "sạch" hơn nhưng khó test/debug bằng trình duyệt, dễ bị quên khi client không set header |
| Không versioning, chỉ additive change | Luôn thêm trường mới, không bao giờ đổi/xoá trường cũ | Đơn giản nhất khi áp dụng được, nhưng không giải quyết được breaking change thực sự cần thiết (đổi kiểu dữ liệu, đổi luồng nghiệp vụ) |
Nguyên tắc thực dụng: trì hoãn breaking change càng lâu càng tốt bằng additive change; khi bắt buộc phải
breaking, URI versioning là lựa chọn dễ vận hành nhất, kèm chính sách rõ ràng về thời gian hỗ trợ song song
nhiều version và deprecation warning (header Sunset) trước khi tắt hẳn version cũ.
🏋️ Bài tập thực hành
Với API /orders từ module trước, triển khai cursor-based pagination cho GET /orders (dùng id làm cursor), chuẩn hoá mọi response lỗi theo RFC 7807, và thêm cơ chế Idempotency-Key cho POST /orders (dùng bảng idempotency_keys trong PostgreSQL). Viết test chứng minh: gửi 2 request POST /orders giống hệt nhau cùng 1 Idempotency-Key chỉ tạo ra đúng 1 đơn hàng.
📚 Tài nguyên học tập
-
RFC 7807 — Problem Details for HTTP APIsChuẩn chính thức cho format lỗi HTTP APIRFC
-
Stripe — Idempotent RequestsCách Stripe triển khai Idempotency-Key trong thực tế productionDocs
-
Stripe — API VersioningChiến lược versioning của một trong những API được tích hợp nhiều nhất thế giớiDocs
✅ Tự đánh giá hoàn thành
- Triển khai được cursor-based pagination hoạt động đúng khi dữ liệu bị chèn/xoá giữa các lần gọi
- Chuẩn hoá format lỗi nhất quán theo RFC 7807 trên toàn bộ API
- Triển khai và test được Idempotency-Key chống retry trùng lặp cho 1 thao tác quan trọng
- Chọn và giải thích được chiến lược versioning phù hợp cho 1 API cụ thể