Backend API Engineering for AI Engineers
Trang chủ / Module 2
📐 Module 2 / 14 · 1 tuần

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.

PaginationIdempotencyVersioning
📌 Vì sao module này quan trọng

Đâ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-basedCursor-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ớnChậm dần — OFFSET 1000000 vẫn phải quét qua 1 triệu dòngNhanh, ổn định — dùng index trực tiếp (WHERE id > cursor)
Dữ liệu bị chèn/xoá khi đang phân trangCó 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ượcVí dụƯu / nhược điểm
URI versioning/v1/orders, /v2/ordersRõ 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 versioningAccept: application/vnd.api+json;version=2URL "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 changeLuô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

Thêm pagination, idempotency, và chuẩn lỗi vào 1 API có sẵn

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

✅ 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ể