Thiết kế API

API là gì trong một bài thiết kế

API là hợp đồng giữa client và server: client được gọi những gì, gửi dữ liệu dạng nào, nhận lại gì, lỗi trông ra sao. Trong phỏng vấn, bước thiết kế API thường đến ngay sau khi chốt yêu cầu chức năng. Mỗi yêu cầu chức năng thường thành một hoặc hai endpoint. Microservices Patterns coi việc định nghĩa API là một phần của thiết kế: API gồm các thao tác và sự kiện mà client dùng, và cần có kế hoạch cho việc API thay đổi theo thời gian.¹

Một API tốt có bốn tính chất:

• Dễ đoán: nhìn tên endpoint là biết nó làm gì.
• An toàn khi gọi lại: mạng chập chờn, client retry không làm trừ tiền hai lần.
• Mở rộng được: thêm trường mới không làm hỏng client cũ (thay đổi tương thích ngược; Microservices Patterns ghi rằng không thể ép mọi client nâng cấp cùng lúc).²
• Có giới hạn: không ai gọi được không giới hạn, không trả về một triệu dòng trong một response.

Vì sao quan trọng trong phỏng vấn

API là chỗ người phỏng vấn kiểm tra bạn đã hiểu bài toán chưa. Liệt kê được POST /bookings với body gồm eventId, seatIds cho thấy bạn biết thực thể chính và luồng chính. Thêm Idempotency-Key cho thấy bạn nghĩ tới retry. Thêm cursor cho thấy bạn nghĩ tới dữ liệu lớn.

Bạn không cần viết đặc tả đầy đủ. Ba tới sáu endpoint chính, mỗi endpoint một dòng, đủ để cả hai bên thống nhất. Dành 3–5 phút cho phần này, rồi chuyển sang kiến trúc (gợi ý của khoá học; Grokking khuyên định nghĩa API ở mức cao để hiểu dữ liệu và tương tác của hệ thống).³

REST theo resource

REST tổ chức API quanh resource (danh từ) và dùng HTTP method làm hành động (động từ). Đây là lựa chọn mặc định cho API công khai và API từ client tới backend. Microservices Patterns định nghĩa resource là một đối tượng nghiệp vụ như Customer hoặc Product (hay một tập hợp chúng), được tham chiếu bằng URL và thao tác bằng các HTTP verb.⁵ Building Microservices ghi GET đọc resource theo cách idempotent còn POST tạo resource mới.⁶

Bảng trên: GET và POST có trong sách; tính idempotent của PUT, PATCH, DELETE là kiến thức HTTP chung, chưa có sách trong thư viện mô tả.⁷

Quy tắc đặt tên (quy ước của khoá học):

• Danh từ số nhiều: /events, /bookings.
• Lồng tối đa một cấp khi có quan hệ sở hữu rõ ràng: /events/42/seats. Sâu hơn thì tách ra: /seats?eventId=42.
• Hành động khó biểu diễn bằng CRUD thì tạo resource cho nó: hủy đơn là POST /orders/9/cancellation hoặc chấp nhận một động từ POST /orders/9:cancel. Chọn một kiểu và dùng nhất quán.
• Lọc, sắp xếp, phân trang qua query string: GET /posts?author=me&sort=-createdAt&limit=20.

Mã trạng thái cần dùng đúng (Building Microservices dùng 202 cho "đã nhận, chưa xử lý" và 201 khi hoàn tất;⁸ Grokking trả 429 khi vượt giới hạn;⁹ các mã còn lại là quy ước HTTP chung⁷): 200 đọc thành công, 201 tạo xong, 202 đã nhận và xử lý sau (job dài), 204 không có body, 400 dữ liệu sai, 401 chưa đăng nhập, 403 không có quyền, 404 không tồn tại, 409 xung đột (ghế đã bị giữ), 429 gọi quá nhiều, 5xx lỗi server.

Ví dụ NestJS cho bài đặt vé:

@Controller("events/:eventId/bookings")
@UseGuards(JwtAuthGuard)
export class BookingController {
  constructor(private readonly bookings: BookingService) {}

  @Post()
  @HttpCode(201)
  create(
    @Param("eventId") eventId: string,
    @Body() dto: CreateBookingDto,
    @Headers("idempotency-key") key: string,
    @Req() req: AuthedRequest,
  ) {
    return this.bookings.reserve(req.user.id, eventId, dto.seatIds, key);
  }
}

REST, GraphQL và gRPC

Microservices Patterns ch.3 chia giao tiếp giữa service thành đồng bộ (REST, gRPC) và bất đồng bộ (message). Ch.8 bàn về API cho client bên ngoài, nơi GraphQL thường xuất hiện ở tầng API gateway.¹⁰¹¹ Sách nêu gRPC là giao thức nhị phân dựa trên message, định nghĩa API bằng Protocol Buffers, chạy trên HTTP/2 và hỗ trợ nhiều ngôn ngữ; Protocol Buffers giúp việc tiến hoá API dễ hơn.¹² Về GraphQL, sách nói client có thể được phép chỉ định dữ liệu cần (tham số expand, fields) hoặc dùng Backends for frontends, và GraphQL được cân nhắc khi cần phục vụ nhiều loại client.¹¹ Ba lựa chọn đồng bộ so sánh như sau (các dòng về cache, streaming, công cụ là kiến thức chung chưa có sách):⁷

Cách chọn thường gặp trong một hệ thống:

Các chi tiết làm API chạy được ở quy mô lớn

Phân trang: offset và cursor

Bảng so sánh offset và cursor là kiến thức chung về database và API, chưa có sách trong thư viện;⁷ Building Microservices chỉ nhắc API có thể cho phép lấy theo lô hoặc duyệt qua toàn bộ danh sách.⁸ Cursor nên là chuỗi mã hóa (base64 của createdAt và id) để client không tự ghép. Response trả kèm nextCursor, null khi hết.

app.get("/posts", async (req, res) => {
  const limit = Math.min(Number(req.query.limit) || 20, 100);
  const after = req.query.after ? decodeCursor(String(req.query.after)) : null;
  const rows = await db.query(
    `SELECT id, body, created_at FROM posts
     WHERE ($1::timestamptz IS NULL OR (created_at, id) < ($1, $2))
     ORDER BY created_at DESC, id DESC LIMIT $3`,
    [after?.createdAt ?? null, after?.id ?? null, limit + 1],
  );
  const page = rows.slice(0, limit);
  const next = rows.length > limit ? encodeCursor(page[page.length - 1]) : null;
  res.json({ data: page, nextCursor: next });
});

Lấy limit + 1 dòng để biết còn trang sau mà không cần COUNT(*).

Idempotency key

Client gửi POST /payments, mạng đứt trước khi nhận response. Client không biết server đã trừ tiền chưa, nên retry. Không có biện pháp gì, khách bị trừ hai lần.

Microservices Patterns giải thích một thao tác là idempotent nếu gọi nhiều lần cho cùng kết quả, ví dụ tạo đơn với ID do client cung cấp, và message handler idempotent thì xử lý trùng vô hại.¹³ Cách giải: client sinh một UUID cho mỗi thao tác và gửi trong header Idempotency-Key. Server lưu kết quả theo key. Lần gọi lại với cùng key trả về đúng kết quả cũ.

Cách dùng header Idempotency-Key và Redis SET NX là kỹ thuật của khoá học, chưa có sách trong thư viện mô tả.⁷ Chi tiết cần nói: key gắn với user để người khác không dùng lại được; nếu key đang ở trạng thái processing thì trả 409 hoặc chờ; giữ key 24 giờ; trong DB nên có thêm unique constraint trên key để chặn cả khi Redis mất dữ liệu.

Versioning

Microservices Patterns khuyên dùng semantic versioning (MAJOR.MINOR.PATCH, MAJOR tăng khi có thay đổi không tương thích) và nêu rằng client thường không thể nâng cấp đồng loạt với service.² Quy tắc: thêm trường tùy chọn thì không cần version mới. Đổi tên, xóa trường, đổi kiểu dữ liệu thì cần. Mobile app cũ sống rất lâu trên máy người dùng, nên version cũ thường phải giữ hàng tháng.

Định dạng lỗi

Dùng một định dạng duy nhất cho mọi lỗi (khuyến nghị của khoá học; chuẩn Problem Details chưa có sách trong thư viện)⁷ hoặc đơn giản hơn:

{
  "error": {
    "code": "SEAT_ALREADY_HELD",
    "message": "Ghế A12 đang được người khác giữ.",
    "details": { "seatId": "A12", "heldUntil": "2026-11-03T10:15:00Z" },
    "requestId": "req_8f2c1a"
  }
}

code cho máy đọc và ổn định giữa các version, message cho người đọc, requestId để tra log. Không trả stack trace ra ngoài.

Xác thực và rate limit

Session, JWT, OAuth

Microservices Patterns mô tả session token (thường là cookie) với session lưu ở server, opaque token cần gọi dịch vụ bảo mật để xác thực nên tăng độ trễ, và JWT tự chứa nên không cần tra cứu nhưng không thể thu hồi từng token, giải pháp là cấp JWT hạn ngắn.⁴ OAuth 2.0 là giao thức uỷ quyền, thường dùng qua dịch vụ hoặc framework có sẵn.¹⁴ Các ưu nhược chi tiết trong bảng trên là đánh giá của khoá học. Cách làm phổ biến: access token JWT hạn ngắn (5–15 phút) cộng refresh token hạn dài lưu ở server, có thể thu hồi. API gateway xác minh JWT một lần và chuyển user id cho service phía sau.

export function auth(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return res.status(401).json({ error: { code: "UNAUTHENTICATED" } });
  try {
    req.user = jwt.verify(token, PUBLIC_KEY, { algorithms: ["RS256"] }) as UserClaims;
    next();
  } catch {
    res.status(401).json({ error: { code: "TOKEN_INVALID" } });
  }
}

Rate limit

Grokking ch.19 mô tả rate limiter đặt trước API: xác định client (theo user id, API key hoặc IP), so với quy tắc, quá giới hạn thì trả 429 Too Many Requests. Các thuật toán hay dùng là token bucket, leaking bucket, fixed window counter, sliding window log, sliding window counter.¹⁵

Những gì nên đưa vào API (tên header cụ thể là quy ước của khoá học;⁷ Grokking nói rate limiter nằm ở lớp API và đếm bằng key-value store):⁹

• Header cho client biết giới hạn: RateLimit-Limit, RateLimit-Remaining, Retry-After khi trả 429.
• Giới hạn khác nhau theo loại endpoint: đọc thoải mái, đăng nhập và gửi OTP rất chặt.
• Đặt ở API gateway, đếm trong Redis để mọi instance dùng chung một bộ đếm.

Chi tiết thiết kế xem bài Rate limiter.

Con số và sizing

Các con số dưới đây là ước lượng của khoá học (quy tắc ước lượng của khoá học, cần load test; nguồn công thức xem Chọn server),¹⁶ dùng để nói chuyện trong phỏng vấn. Các số về kích thước response, JWT, Redis không lấy từ sách.

Ví dụ: 10 triệu người dùng hoạt động mỗi ngày, mỗi người 50 request. Trung bình 500 triệu / 86.400 ≈ 5.800 req/s. Peak ×5 ≈ 29.000 req/s. Số instance ≈ 29.000 / 600 ≈ 49 instance 2 vCPU. Grokking dùng mốc ~8.000 RPS mỗi server khi tính nhẩm và nêu máy chỉ phục vụ nội dung tĩnh từ RAM có thể tới khoảng 500 nghìn RPS còn tác vụ nặng như xử lý ảnh chỉ khoảng 50 RPS; xem 8.000 như giới hạn trên.¹⁷

Sai lầm hay gặp

(Các lỗi dưới đây là kinh nghiệm của khoá học, đối chiếu thêm với các mục có nguồn ở trên.)⁷

• Động từ trong URL cho mọi thứ: /getUser, /createOrder. Dùng resource và method.
• Trả về toàn bộ danh sách không phân trang. Ngày đầu có 50 dòng, một năm sau có 5 triệu dòng.
• Dùng offset cho feed vô hạn. Trang sâu chậm, bài mới chèn vào làm lặp bài.
• Không có idempotency cho thao tác tiền và đặt chỗ. Retry tự động của client, của load balancer, của thư viện HTTP sẽ gây trùng.
• Tin dữ liệu client gửi lên. Giá, userId, quyền phải lấy từ server và token.
• JWT hạn 30 ngày không có cách thu hồi. Token bị lộ là mất quyền kiểm soát 30 ngày.
• Trả 200 kèm {"success": false}. Load balancer, monitoring và retry đều dựa vào status code.

Khi nào nhắc tới trong phỏng vấn

Bảng trên là gợi ý của khoá học; nguồn của từng ý nằm ở bài thiết kế tương ứng.¹⁶ Cách nhìn API gateway chịu trách nhiệm xác thực và định tuyến có trong Microservices Patterns ch.8.¹⁸

Đọc tiếp: Mạng cơ bản cho tầng truyền tải bên dưới, API gateway cho xác thực và rate limit ở rìa hệ thống, Quy trình nhiều bước cho API của các thao tác kéo dài.

Nguồn trích dẫn

1. Microservices Patterns (file .zip, tải về giải nén) · ch.3 Interprocess communication · §3.1.2 Defining APIs in a microservice architecture và §3.1.3 Evolving APIs. ↩

2. Microservices Patterns (file .zip, tải về giải nén) · ch.3 · §3.1.3 Evolving APIs (mục "Use semantic versioning"). ↩ ↩²

3. Grokking Modern System Design · ch.2 System Design Interviews · bài "How to Perform Well", mục "Discuss the components" (định nghĩa API người dùng ở mức cao). ↩

4. Microservices Patterns (file .zip, tải về giải nén) · ch.11 Developing production-ready services · §11.1.2 Implementing security in a microservice architecture (mục "Using JWTs to pass user identity and roles"; session token ở §11.1.1). ↩ ↩²

5. Microservices Patterns (file .zip, tải về giải nén) · ch.3 · §3.2.1 Using REST. ↩

6. Building Microservices (file .zip, tải về giải nén) · ch.4 Integration · mục "REST and HTTP". ↩

7. Chưa có nguồn trong thư viện: không sách nào trong thư viện mô tả tính idempotent của PUT/PATCH/DELETE, ý nghĩa đầy đủ các mã trạng thái, so sánh cache giữa REST và GraphQL, N+1 và DataLoader, phân trang cursor, header Idempotency-Key, Problem Details hay tên header rate limit; các phần này chỉ nêu khái niệm cơ bản. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹

8. Building Microservices (file .zip, tải về giải nén) · ch.4 Integration · phần bàn về gọi theo lô (batch): trả HTTP 202 cho yêu cầu đã nhận, sau đó 201 Created khi xong; cũng nêu việc lấy theo danh sách ID hoặc duyệt qua toàn bộ. ↩ ↩²

9. Grokking Modern System Design · ch.19 Rate Limiter · bài thiết kế rate limiter, phần trả HTTP 429 Too Many Requests khi vượt giới hạn. ↩ ↩²

10. Microservices Patterns (file .zip, tải về giải nén) · ch.3 · §3.1.1 Interaction styles và §3.2 Communicating using the synchronous Remote procedure invocation pattern. ↩

11. Microservices Patterns (file .zip, tải về giải nén) · ch.8 External API patterns · §8.3.3 Implementing an API gateway using GraphQL (và §8.1 API design issues). ↩ ↩²

12. Microservices Patterns (file .zip, tải về giải nén) · ch.3 · §3.2.2 Using gRPC và §3.1.4 Message formats. ↩

13. Microservices Patterns (file .zip, tải về giải nén) · ch.3 · §3.3.6 Handling duplicate messages (mục "Writing idempotent message handlers"). ↩

14. Microservices Patterns (file .zip, tải về giải nén) · ch.11 · §11.1.2 (mục "Using OAuth 2.0 in a microservice architecture"). ↩

15. Grokking Modern System Design · ch.19 Rate Limiter · phần thuật toán: Token bucket, Leaking bucket, Fixed window counter, Sliding window log, Sliding window counter. ↩

16. Quy tắc ước lượng của khoá học, xem bài Chọn server. Không phải số liệu trích từ sách. ↩ ↩²

17. Grokking Modern System Design · ch.5 Back-of-the-envelope Calculations · bài "Put Back-of-the-envelope Numbers in Perspective", mục "Requests estimation". ↩

18. Microservices Patterns (file .zip, tải về giải nén) · ch.8 External API patterns · §8.2 The API gateway pattern. ↩