Cụm bài REST API nâng cao: 1. Method idempotent, URL và phân trang · 2. Async job, Idempotency-Key và tài liệu API
Bài này giải hai việc mà API đồng bộ “request vào, response ra” không làm nổi: thao tác mất vài phút (export file 500 MB) và thao tác không được chạy hai lần (thanh toán bị retry). Sau đó là response envelope với mã lỗi thống nhất và cách viết tài liệu API cho nhiều team dùng chung. Đọc xong, bạn thiết kế được async job và Idempotency-Key đầy đủ.
Nên đọc trước: phần 1 (safe và idempotent, phân trang), Web và HTTP (status code như 202, 303, 409, 410).
1. Case study: export file 500 MB
Ý chính: đừng làm export nặng trong một request đồng bộ. Tách thành “tạo job” và “lấy kết quả”, worker xử lý theo luồng, file đi thẳng từ object storage tới client.
1.1. Bài toán
Ý chính: API đồng bộ cho việc vài phút sẽ dính timeout, hết bộ nhớ, chiếm tài nguyên và không làm tiếp được khi đứt mạng.
Admin bấm “Xuất Excel” danh sách sản phẩm; với khách lớn, file khoảng 500 MB, tạo mất vài phút. Thiết kế ngây thơ: query, ghi file, trả file trong cùng request.
- Timeout: Nginx
proxy_read_timeoutmặc định 60 giây, AWS ALB idle timeout 60 giây, Cloudflare khoảng 100 giây. Client nhận504nhưng server vẫn chạy; người dùng bấm lại thành hai job nặng. - OOM (out of memory, hết heap):
findAll()nạp cả kết quả vàoList, persistence context của JPA giữ mọi entity, thư viện Excel giữ cả workbook. 500 MB dữ liệu thành vài GB heap. - Giữ tài nguyên: thread servlet và connection DB bị chiếm vài phút; vài người export cùng lúc là pool cạn.
- Không retry được: đứt mạng ở phút thứ 4 là làm lại từ đầu.
1.2. Thiết kế: async job
Ý chính: POST tạo job trả 202 Accepted + Location, GET hỏi trạng thái, GET /result chuyển hướng tới presigned URL (URL ký sẵn, hết hạn sau ít phút).
POST /v1/exportsbody{"type": "PRODUCTS", "filter": {"name": "pen"}}→202 Accepted, headerLocation: /v1/jobs/001, body{"job_id": "001", "status": "PENDING", "issued_at": 1763443200000}.GET /v1/jobs/001→{"status": "PROCESSING", "progress": 42}, rồi{"status": "DONE", "updated_at": ...}hoặc{"status": "FAILED", "error": {...}}.GET /v1/jobs/001/result→302/303tới presigned URL của object storage (S3, MinIO, GCS), hạn ví dụ 15 phút. File không đi qua app server.
Worker đọc và ghi theo luồng (stream: xử lý từng dòng rồi bỏ, không gom vào RAM), nên bộ nhớ không đổi dù file to cỡ nào.
Code worker export theo luồng và chi tiết theo từng DB
@Transactional(readOnly = true) // PostgreSQL: driver chỉ stream khi autocommit tắt
public void runExport(ExportJob job, OutputStream out) {
jdbcTemplate.setFetchSize(1_000); // lấy 1000 dòng mỗi lượt thay vì cả kết quả
try (var writer = new BufferedWriter(new OutputStreamWriter(out, StandardCharsets.UTF_8))) {
jdbcTemplate.query(
"SELECT id, name, price FROM product WHERE name ILIKE ? ORDER BY id",
rs -> { // RowCallbackHandler: từng dòng, không gom List
writer.write(rs.getLong(1) + "," + csv(rs.getString(2)) + "," + rs.getBigDecimal(3));
writer.newLine();
},
"%" + job.filterName() + "%");
} catch (IOException e) {
throw new UncheckedIOException(e);
}
}
// out = stream multipart upload lên object storage, không phải file tạm khổng lồ trên đĩa pod
- PostgreSQL: driver chỉ dùng cursor phía server khi
autoCommit=falsevàfetchSize > 0. - MySQL Connector/J: cần
useCursorFetch=true(hoặcfetchSize = Integer.MIN_VALUEđể stream từng dòng). - Spring Data
Stream<T>: phải trong transaction vàdetachentity sau mỗi dòng, nếu không persistence context vẫn phình. - Excel: dùng API streaming (Apache POI
SXSSFWorkbook) hoặc xuất CSV.
1.3. Polling, webhook hay đẩy realtime
Ý chính: polling (client hỏi định kỳ) đơn giản nhất; webhook (server gọi lại URL của client) tiết kiệm nhưng phức tạp; SSE/WebSocket cho UI cần tiến độ tức thì. Dù chọn gì, vẫn giữ API trạng thái.
sequenceDiagram
participant C as Client
participant A as API
participant W as Worker
participant S as Object storage
C->>A: POST /v1/exports
A-->>C: 202 Accepted, Location /v1/jobs/001
A->>W: đưa job vào queue
loop Polling có backoff
C->>A: GET /v1/jobs/001
A-->>C: PROCESSING, Retry-After 5
end
W->>S: upload file theo multipart
W->>A: cập nhật job DONE
C->>A: GET /v1/jobs/001
A-->>C: DONE
C->>A: GET /v1/jobs/001/result
A-->>C: 303 tới presigned URL
C->>S: tải file trực tiếp
Với webhook, client gửi callback_url khi tạo job (hoặc đăng ký trước). Xong việc, server gọi POST callback_url với {"job_id": "001", "status": "DONE"}. Thực tế hay kết hợp: webhook để báo, API trạng thái làm dự phòng khi webhook mất.
Bảng so sánh polling, webhook và SSE/WebSocket
1.4. Các kiểu hỏng và cách xử lý
Ý chính: job async hỏng theo bốn kiểu: worker chết, kết quả hết hạn, lộ kết quả cho người khác, quá tải. Mỗi kiểu có một cách chặn cụ thể.
- Worker chết giữa chừng: job kẹt
PROCESSING. Worker cầm job bằng lease (quyền giữ có hạn,locked_until), gia hạn định kỳ; hết lease thì worker khác nhặt lại (SELECT ... FOR UPDATE SKIP LOCKED, xem transaction và locking). Quá số lần thử thìFAILED. - Kết quả hết hạn: lifecycle rule xoá file sau N ngày;
GET /resulttrả410 Gone, không phải500. - Phân quyền:
GET /jobs/{id}kiểm tra job thuộc user hiện tại. Id tăng dần dễ đoán: dùng UUID và vẫn kiểm tra quyền. - Quá tải: giới hạn job đồng thời mỗi user/tenant, vượt thì
429.
Code ký và xác minh chữ ký HMAC của webhook
static String sign(byte[] secret, long ts, String body) throws Exception {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret, "HmacSHA256"));
return HexFormat.of().formatHex(mac.doFinal((ts + "." + body).getBytes(StandardCharsets.UTF_8)));
}
static boolean verify(byte[] secret, String header, String rawBody, long nowEpochSec) throws Exception {
Map<String, String> kv = new HashMap<>();
for (String p : header.split(",")) { String[] x = p.split("=", 2); kv.put(x[0], x[1]); }
long ts = Long.parseLong(kv.get("t"));
if (Math.abs(nowEpochSec - ts) > 300) return false; // quá 5 phút: coi là replay
byte[] expected = sign(secret, ts, rawBody).getBytes(StandardCharsets.US_ASCII);
return MessageDigest.isEqual(expected, kv.get("v1").getBytes(StandardCharsets.US_ASCII));
}
// Chạy thử: đúng chữ ký -> true; sửa "DONE" thành "FAILED" -> false; gửi lại sau 1 giờ -> false
2. Case study: request trùng khi thanh toán
Ý chính: client gửi một Idempotency-Key cho mỗi thao tác; server lưu key cùng response lần đầu và trả lại đúng response đó cho mọi lần retry.
2.1. Bài toán
Ý chính: client bị timeout không biết tiền đã trừ chưa nên retry; mỗi request trùng là tiền thật.
Client gọi POST /payment-service/v1/payments. Server trừ tiền xong thì kết nối đứt, client nhận timeout và retry. Hoặc người dùng bấm “Thanh toán” hai lần, hoặc kẻ tấn công bắt request và gửi lại (replay).
Lời giải của khoá học: client sinh Idempotency-Key (UUID) cho mỗi thao tác, gửi trong header. Server lưu key vào cột có UNIQUE constraint; request thứ hai cùng key bị DB từ chối (“Duplicated!”).
2.2. Những gì lời giải gốc còn thiếu
Ý chính: UNIQUE constraint chỉ chặn bản ghi thứ hai. API idempotent đầy đủ còn phải trả lời sáu câu dưới đây.
- Retry nhận được gì? Trả “Duplicated!” thì client tưởng thanh toán thất bại. Phải lưu response lần đầu và trả lại y nguyên (cùng status, cùng body).
- Cùng key, khác body? (client có bug dùng lại key) Lưu hash body; khác thì trả
422(Stripe làm vậy), không trả kết quả giao dịch cũ. - Hai request cùng key tới cùng lúc? Hoặc cho lần hai chờ (insert key trong cùng transaction, DB chặn ở unique index), hoặc trả
409 Conflictđể client thử lại sau. - Phạm vi key: unique theo
(client_id, key), không toàn cục. - Hết hạn: giữ key 24 giờ (Stripe) đến vài ngày, quá hạn thì job dọn dẹp xoá.
- Lỗi nào thì lưu? Lỗi validation (
400) không lưu, để client sửa rồi gửi lại cùng key. Kết quả nghiệp vụ đã chốt (thành công, “không đủ số dư”) thì lưu. Lỗi hạ tầng giữa chừng thì rollback cả key để retry chạy lại.
flowchart TD
A[Request + Idempotency-Key] --> B{Key đã có?}
B -- Chưa --> C[Insert key IN_PROGRESS] --> D[Xử lý nghiệp vụ] --> E[Lưu status + body, COMPLETED] --> F[Trả response]
B -- Có, hash body khác --> G[422 key bị dùng lại]
B -- Có, đang xử lý --> H[409 hoặc chờ]
B -- Có, COMPLETED --> I[Trả lại response đã lưu]
Bài Idempotency từ API đến Kafka và cổng thanh toán cài và chạy thử luồng này trên PostgreSQL (20 request trùng key cùng lúc chỉ tạo một giao dịch), kèm idempotency ở consumer Kafka và IPN cổng thanh toán.
Key nên do client sinh (UUID cho mỗi thao tác, giữ nguyên khi retry), vì chỉ client biết hai request là cùng một ý định.
Ba cách sinh key: client, server suy ra, server cấp trước
3. Response envelope và mã lỗi 6 chữ số
Ý chính: envelope (lớp bọc chung meta + data) cho mọi response cùng một hình dạng. Mã lỗi 6 chữ số chỉ có ích khi 3 chữ số đầu luôn bằng HTTP status thật.
Template của khoá học:
{
"meta": {
"code": "200000",
"type": "SUCCESS",
"message": "Payment created",
"service_id": "payment-service",
"request_id": "c0a8012e-7f1d-4b6a-9e1b-6f3c2d1a0b9e",
"extra_meta": {}
},
"data": { "payment_id": "P-7781", "status": "COMPLETED" }
}
Lỗi nghiệp vụ: meta.code = "400001", type = "INSUFFICIENT_DEBIT_AMOUNT", data = null. Mã 6 chữ số = HTTP status (3 chữ số) + số thứ tự nghiệp vụ (3 chữ số): nhìn 404003 biết ngay nhóm “không tìm thấy”. type là hằng số ổn định để client switch; message cho người đọc, có thể đổi.
4. Viết tài liệu API
Ý chính: tài liệu tốt mô tả rõ request/response, liệt kê mọi lỗi có thể xảy ra, có cURL chạy được; phần cơ học nên sinh tự động để không lệch với code.
4.1. Tài liệu cho một endpoint
Ý chính: mỗi endpoint cần spec chung, bảng field và bảng lỗi. Cột Description phải nói logic nghiệp vụ, format và ví dụ.
- Bảng field: Parameter | Type | Required | Default | Description.
- Bảng lỗi: HTTP status | code | type | description, ví dụ
422 | 422001 | INSUFFICIENT_DEBIT_AMOUNT | Số dư tài khoản ghi nợ không đủ.
Template gốc có hai lỗi copy-paste (tham số phân trang trên một POST, cURL lấy từ API khác). Chống bằng OpenAPI và chạy cURL mẫu trong CI.
Template mẫu cho endpoint “Make payment” và lỗi copy-paste
| Mục | Nội dung |
|---|---|
| Name | Make payment |
| Description | Tạo giao dịch chuyển tiền giữa hai tài khoản thường |
| URL | https://{{host}}/payment-service/v1/payments |
| Method | POST |
| Headers | Content-Type: application/json, Authorization: Bearer <token>, Idempotency-Key: <uuid> (bắt buộc) |
| Request body | debit_account, credit_account, amount |
| Response | Envelope meta + data |
Ví dụ Description tốt cho amount: “integer, đơn vị nhỏ nhất của tiền tệ (VND không có phần lẻ), > 0, ≤ 500.000.000; ví dụ 150000”.
4.2. API map
Ý chính: API map là mục lục trả lời “luồng này gọi API nào, theo thứ tự nào, ai chịu trách nhiệm”, xếp theo luồng và theo resource.
- Theo luồng (flow): Flow ID, tên luồng (Payment, Get balance), thứ tự gọi, link spec từng API, PIC (person in charge, người chịu trách nhiệm).
- Theo resource: Payment, Order, Account… mỗi resource liệt kê mọi endpoint của nó.
Bắt đầu bằng bảng tính; quy mô lớn thì dùng developer portal (Backstage) hay API catalog. Tài liệu kiến trúc rộng hơn (C4, ADR) ở bài Viết tài liệu kiến trúc.
Ví dụ API map và Spring REST Docs
| Flow | Bước | API | Service | PIC |
|---|---|---|---|---|
| F01 Payment | 1 | GET /account-service/v1/accounts/{id}/balance |
account | Team A |
| F01 Payment | 2 | POST /payment-service/v1/payments |
payment | Team B |
| F01 Payment | 3 | GET /payment-service/v1/payments/{id} |
payment | Team B |
Bài tập
Bài 1: Hợp đồng API cho export bất đồng bộ
Đề: viết đầy đủ các endpoint, status code và trạng thái job cho tính năng export.
Lời giải bài 1
- Trạng thái:
PENDING → PROCESSING → DONE | FAILED | EXPIRED. POST /v1/exports→202+Location; trùng Idempotency-Key → trả lại job cũ; vượt hạn mức →429.GET /v1/jobs/{id}→200+Retry-Afterkhi chưa xong; job của người khác →404(không lộ sự tồn tại).GET /v1/jobs/{id}/result→303presigned URL khiDONE,409khi chưa xong,410khi file đã hết hạn.
Bài 2: Viết tài liệu cho API “Make payment”
Đề: dùng template ở phần 4, viết đủ spec, bảng field, bảng lỗi và cURL.
Lời giải bài 2
curl -X POST "https://$HOST/payment-service/v1/payments" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-H "Idempotency-Key: 5f0e4c1a-2b7d-4e8f-9a3c-1d2e3f4a5b6c" \
-d '{"debit_account": "1001", "credit_account": "2002", "amount": 150000}'
| HTTP | code | type | Ý nghĩa |
|---|---|---|---|
| 201 | 201000 | SUCCESS | Tạo giao dịch thành công |
| 400 | 400001 | INVALID_AMOUNT | amount ≤ 0 hoặc vượt hạn mức |
| 400 | 400002 | MISSING_IDEMPOTENCY_KEY | Thiếu header bắt buộc |
| 403 | 403001 | DEBIT_ACCOUNT_LOCKED | Tài khoản ghi nợ bị khoá |
| 409 | 409001 | REQUEST_IN_PROGRESS | Request cùng key đang được xử lý |
| 422 | 422001 | INSUFFICIENT_DEBIT_AMOUNT | Số dư không đủ |
| 422 | 422002 | IDEMPOTENCY_KEY_REUSED | Cùng key nhưng body khác |
Ghi nhớ
- Giải thích được vì sao export vài trăm MB phải là async job, và kể đủ bốn thứ gãy khi làm đồng bộ.
- Vẽ được luồng
POST→202+Location→ polling →303presigned URL, và biết khi nào chọn webhook hay SSE. - Biết ký và xác minh webhook: HMAC trên raw body, timestamp chống replay, dedupe
event_id. - Trả lời được sáu câu mà UNIQUE constraint chưa giải quyết cho Idempotency-Key.
- Biết quy tắc mã lỗi 6 chữ số và khi nào chọn envelope riêng hay Problem Details.
Câu hỏi phỏng vấn
Junior
Vì sao không dùng GET để tạo job export?
Vì GET phải safe: nhiều thứ được phép gọi lại GET, và mỗi lần gọi lại sẽ tạo thêm một job nặng.
Crawler, prefetch, link preview và retry tự động đều có thể gọi lại GET. Tạo job là tạo resource nên dùng POST, trả 202 Accepted cùng header Location trỏ tới resource job.
Mid
Khi nào trả 202 Accepted thay vì 201 Created?
201 khi resource đã tạo xong ngay trong request; 202 khi server mới nhận yêu cầu và sẽ xử lý sau.
201 kèm Location tới resource. 202 nên kèm Location tới resource job để client theo dõi, có thể kèm Retry-After. 202 không hứa yêu cầu sẽ thành công.
Mã lỗi nghiệp vụ 6 chữ số có lợi gì và cần quy tắc gì?
Nhìn mã là biết nhóm lỗi (3 chữ số đầu là HTTP status), nhưng chỉ đúng khi prefix luôn khớp status thật.
3 chữ số sau là số thứ tự nghiệp vụ; type là hằng số ổn định để client switch. Quy tắc: prefix khớp HTTP status thật, mỗi mã một ý nghĩa duy nhất có trong tài liệu, không tái sử dụng mã cho ý nghĩa khác. Kiểm sự khớp bằng test tự động.
Senior
Thiết kế API export file vài trăm MB thế nào?
Làm async job: POST trả 202 + Location, worker xử lý theo luồng, kết quả qua presigned URL; không làm đồng bộ.
- Đồng bộ thì dính timeout của LB/gateway (thường 60 giây), OOM, giữ thread và connection vài phút.
- Worker đọc DB theo luồng (fetch size, cursor phía server, không gom List), ghi multipart lên object storage.
- Client polling có Retry-After hoặc nhận webhook; tải qua presigned URL có hạn.
- Worker chết: lease và retry có giới hạn. Thêm giới hạn job đồng thời mỗi tenant, kiểm tra quyền trên job, dọn file bằng lifecycle rule.
Idempotency-Key kiểu Stripe hoạt động thế nào?
Client gửi một key cho mỗi thao tác; server lưu key cùng response lần đầu và trả lại y nguyên cho mọi lần retry.
- Server lưu (client, key) với UNIQUE constraint, hash body, trạng thái và response.
- Lần đầu: insert key, xử lý, lưu status + body.
- Lần sau cùng key: body khác → 422, đang xử lý → 409 (hoặc chờ), xong rồi → trả đúng response đã lưu.
- Lỗi validation không lưu để client sửa; lỗi hạ tầng giữa chừng thì rollback key. Key hết hạn sau khoảng 24 giờ.
Polling, webhook, SSE/WebSocket: chọn thế nào cho thông báo job xong?
Polling cho tải thấp và mọi client, webhook cho B2B và thanh toán, SSE/WebSocket cho UI cần tiến độ tức thì; luôn giữ API trạng thái làm dự phòng.
- Polling: đơn giản, chạy mọi client, tốn request rỗng.
- Webhook: tiết kiệm, gần realtime, nhưng cần receiver có URL công khai, chữ ký HMAC, retry với backoff, receiver idempotent.
- SSE/WebSocket: giữ kết nối lâu, phải phát sự kiện giữa các instance.
Bạn bảo vệ webhook receiver thế nào?
Xác minh chữ ký HMAC trên raw body, chống replay bằng timestamp, dedupe theo event_id, và với thanh toán thì gọi lại nhà cung cấp để xác nhận.
- So chữ ký bằng phép so sánh thời gian hằng; chỉ nhận qua HTTPS.
- Dedupe theo event_id vì bên gửi sẽ retry.
- Trả 2xx nhanh rồi xử lý bất đồng bộ để không bị timeout và gửi lại.
- Dữ liệu quan trọng: không tin tuyệt đối nội dung webhook, gọi API nhà cung cấp để xác nhận trạng thái.
Response envelope meta/data có nhược điểm gì?
Không chuẩn, client phải bóc data mọi chỗ, và dễ dẫn tới trả HTTP 200 cho cả lỗi.
Trả 200 cho lỗi làm hỏng retry, cache, alert dựa trên status. Nếu dùng, HTTP status phải luôn đúng và mã nghiệp vụ khớp status. Problem Details (RFC 9457) là lựa chọn chuẩn cho lỗi, mã nghiệp vụ để trong trường mở rộng.
Từ vựng tiếng Anh
| Term | Phát âm | Nghĩa | Ví dụ câu tiếng Anh dùng trong phỏng vấn |
|---|---|---|---|
| idempotency key | /ˌaɪ.dəmˈpoʊ.tən.si kiː/ | khoá chống xử lý trùng | “The client reuses the same idempotency key on every retry.” |
| async job | /ˈeɪ.sɪŋk dʒɑːb/ | tác vụ bất đồng bộ | “We turned the export into an async job that returns 202.” |
| presigned URL | /ˌpriːˈsaɪnd ˌjuː.ɑːrˈel/ | URL ký sẵn có hạn | “The result is downloaded through a presigned URL that expires in fifteen minutes.” |
| polling | /ˈpoʊ.lɪŋ/ | hỏi định kỳ | “Polling is fine for exports, but it wastes requests at scale.” |
| webhook | /ˈweb.hʊk/ | callback qua HTTP | “Partners receive a webhook when the payment settles.” |
| replay attack | /ˈriː.pleɪ əˈtæk/ | tấn công gửi lại | “The timestamp in the signature protects us against replay attacks.” |
| envelope | /ˈen.və.loʊp/ | lớp bọc response | “Every response uses the same envelope with meta and data.” |
| person in charge (PIC) | /ˈpɜːr.sən ɪn tʃɑːrdʒ/ | người chịu trách nhiệm | “The API map lists the person in charge of each endpoint.” |
| lease | /liːs/ | quyền giữ việc có thời hạn | “A worker holds a lease on the job and renews it while it runs.” |
| out of memory (OOM) | /aʊt əv ˈmem.ər.i/ | hết bộ nhớ | “Loading the whole result set into a list caused an out-of-memory error.” |
Ghi chép dựa trên khoá Advanced Backend (Ronin Engineer), viết lại theo cách hiểu của mình.