Scalable RESTful APIs: Auth, Caching & DB Optimization

Part 1 (English): Building Scalable RESTful APIs — Authentication, Caching, and Database Optimization

Generating standard CRUD endpoints has become trivial with modern tooling and AI code generators. However, what distinguishes a senior software engineer from a junior coder is the ability to architect systems that remain performant, resilient, and maintainable under production traffic. When request volumes surge and relational data expands, poorly structured APIs crumble under database bottlenecks and architectural coupling.

This guide explores four cornerstone patterns of high-performance backend engineering: resilient token authentication, database indexing mechanics, eradicating ORM query inefficiencies, and isolating business logic through Clean Architecture.

1. Bulletproof Authentication: JWT & Secure Refresh Token Rotation

Storing user session state directly in backend server memory breaks horizontal scalability. A stateless JWT approach resolves this, but naive implementations introduce severe security vulnerabilities (such as stolen long-lived tokens).

• Short-Lived Access Token (10–15 mins): Sent via memory or Authorization header. Contains minimal user claims (sub, role). If intercepted, the attack window is extremely short.
• Refresh Token Rotation Pattern: Stored in an httpOnly, Secure, SameSite=Strict cookie. Each time the client exchanges a refresh token for a new access token, the used refresh token is invalidated and immediately replaced with a brand new one.
• Replay Detection: If a compromised refresh token is reused, the authorization service treats this as an active breach, immediately revoking all refresh tokens associated with that user family.

// Conceptual Refresh Token Rotation Controller
export async function handleTokenRefresh(req, res) {
  const incomingToken = req.cookies.refreshToken;
  if (!incomingToken) return res.status(401).json({ error: "Missing token" });

  const tokenRecord = await db.refreshTokens.findOne({ token: incomingToken });
  
  // Reuse detection: Token has already been used!
  if (tokenRecord && tokenRecord.isRevoked) {
    await db.refreshTokens.updateMany({ userId: tokenRecord.userId }, { $set: { isRevoked: true } });
    return res.status(403).json({ error: "Compromised token reuse detected. All sessions terminated." });
  }

  // Issue new token pair & invalidate old one atomically
  const newAccessToken = signJwt({ sub: tokenRecord.userId }, "15m");
  const newRefreshToken = generateSecureOpaqueToken();

  await db.refreshTokens.updateOne({ token: incomingToken }, { $set: { isRevoked: true } });
  await db.refreshTokens.insertOne({ token: newRefreshToken, userId: tokenRecord.userId, expiresAt: new Date(Date.now() + 7 * 86400000) });

  res.cookie("refreshToken", newRefreshToken, { httpOnly: true, secure: true, sameSite: "strict" });
  return res.json({ accessToken: newAccessToken });
}

2. Database Performance: Indexing Mechanics & Execution Plans

An unindexed database query causes a Full Table Scan ($O(N)$ complexity), reading every single disk page. With proper B-Tree indexing, lookups drop to $O(log N)$ tree traversal.

• Composite Indexes (Left-to-Right Rule): If you index (status, createdAt), queries filtering by status or status + createdAt will utilize the index. A query filtering only by createdAt cannot leverage this index.
• Always Inspect Execution Plans: Run EXPLAIN ANALYZE in SQL or .explain("executionStats") in MongoDB. Look out for Seq Scan or COLLSCAN on large datasets.
• Avoid Over-Indexing: Each index speeds up reads but incurs memory overhead and slows down INSERT, UPDATE, and DELETE operations as indexes must be rebalanced.

3. Defeating the Infamous N+1 Query Problem

The $N+1$ problem occurs when an ORM executes 1 initial query to fetch a parent list, followed by $N$ separate queries inside a loop to retrieve related child records.

// ❌ NAIVE APPROACH (Triggers N+1 Queries)
const authors = await db.authors.findMany(); // 1 Query
for (const author of authors) {
  // Triggers N individual roundtrips to the database!
  author.books = await db.books.findMany({ authorId: author.id });
}

// ✅ OPTIMIZED APPROACH (Eager Loading / Batching)
// Executes exactly 2 efficient queries with an IN-clause:
const authors = await db.authors.findMany({
  include: { books: true } // Translates to SELECT * FROM books WHERE author_id IN (...)
});

Dataloader Pattern: In GraphQL or modular microservices, employ the DataLoader batching library to coalesce individual primary-key lookups across a single tick of the event loop into a single grouped query.

4. Decoupling Code with Clean Architecture & Repository Pattern

Embedding database queries directly into route controllers binds your application logic to a specific database provider and makes unit testing impossible without live database connections.

• Domain Layer: Pure business entities and validation rules independent of any framework.
• Application Layer (Use Cases): Business logic orchestrating entities. Interacts with repositories only through abstractions/interfaces.
• Infrastructure Layer: Concrete implementations (Prisma, Mongoose, TypeORM, Redis cache, email providers).
• Presentation Layer: HTTP route handlers, API controllers, and response formatting.

Phần 2 (Tiếng Việt): Thiết Kế RESTful API Mở Rộng — Xác Thực, Caching & Tối Ưu Hóa Database

Viết các API CRUD cơ bản là điều mà bất kỳ lập trình viên mới vào nghề hoặc các công cụ AI đều có thể tạo ra trong vài giây. Tuy nhiên, điều tạo nên sự khác biệt của một kỹ sư backend dày dặn kinh nghiệm chính là năng lực thiết kế những hệ thống giữ vững tốc độ, ổn định và bảo mật cao khi lưu lượng truy cập (traffic) thực tế tăng vọt.

Bài viết này phân tích 4 trụ cột kỹ thuật nền tảng: cơ chế xác thực luân phiên token, chiến lược đánh chỉ mục database, giải quyết triệt để lỗi $N+1$ query trong ORM, và kiến trúc phân tầng Clean Architecture.

1. Luồng Xác Thực Bền Vững: JWT Ngắn Hạn & Refresh Token Rotation

Lưu trữ session người dùng trên RAM của server sẽ phá vỡ khả năng mở rộng quy mô đa máy chủ (Horizontal Scaling). Giải pháp stateless với JWT là tiêu chuẩn, nhưng nếu không thiết kế luồng an toàn thì token có thể bị đánh cắp.

• Access Token Ngắn Hạn (10–15 phút): Chứa thông tin nhận diện cơ bản (User ID, Role). Nếu vô tình bị lộ, thời gian hacker có thể lợi dụng là rất ngắn.
• Refresh Token Rotation (Luân phiên Token): Lưu trữ trong cookie httpOnly, Secure, SameSite=Strict để chống tấn công XSS. Mỗi lần client gửi Refresh Token lên để xin Access Token mới, server sẽ hủy ngay token cũ và cấp lại một cặp token hoàn toàn mới.
• Phát hiện Token Bị Tái Sử Dụng (Replay Detection): Nếu một Refresh Token đã bị hủy lại được gửi lên lần nữa, hệ thống lập tức hiểu rằng token đã bị rò rỉ và tự động thu hồi (revoke) toàn bộ các session của tài khoản đó để bảo vệ người dùng.

2. Tối Ưu Hiệu Năng Truy Vấn Database: Bản Chất Index & Execution Plan

Một truy vấn không có index sẽ buộc database phải thực hiện quét toàn bộ bảng (Full Table Scan) với độ phức tạp $O(N)$. Khi gắn index cây B-Tree hợp lý, độ phức tạp giảm xuống mức $O(log N)$.

• Quy tắc từ trái sang phải của Composite Index: Nếu tạo chỉ mục tổng hợp trên hai cột (status, createdAt), database sẽ tối ưu cho các truy vấn lọc theo status hoặc cả status + createdAt. Truy vấn chỉ lọc theo createdAt sẽ không sử dụng được index này.
• Đọc hiểu Execution Plan: Luôn chủ động chạy EXPLAIN ANALYZE trên SQL hoặc .explain("executionStats") trên MongoDB. Cảnh giác với các dấu hiệu Seq Scan hay COLLSCAN trên các bảng hàng triệu dòng.
• Tránh lạm dụng quá nhiều Index: Index giúp đọc nhanh nhưng sẽ làm chậm đáng kể các thao tác INSERT, UPDATE, DELETE vì database phải tính toán lại cây chỉ mục.

3. Giải Quyết Triệt Để Lỗi Kinh Điển N+1 Query

Lỗi $N+1$ xảy ra khi lập trình viên dùng ORM thực hiện 1 truy vấn lấy danh sách cha, sau đó dùng vòng lặp gọi thêm $N$ truy vấn con đến database.

// ❌ CODE GÂY LỖI N+1 QUERIES
const users = await db.users.findMany(); // 1 query
for (const user of users) {
  // Gửi N request riêng lẻ xuống database trong vòng lặp!
  user.orders = await db.orders.findMany({ userId: user.id });
}

// ✅ CÁCH KHẮC PHỤC: EAGER LOADING
// Chỉ thực thi đúng 2 query tối ưu với mệnh đề IN:
const users = await db.users.findMany({
  include: { orders: true }
});

4. Phân Tầng Mã Nguồn Với Clean Architecture & Repository Pattern

Viết trực tiếp câu lệnh database vào controller khiến code bị ràng buộc cứng (tight coupling) vào công nghệ cụ thể và không thể viết Unit Test một cách độc lập.

• Domain Layer: Chứa logic nghiệp vụ thuần túy, không phụ thuộc vào bất kỳ framework hay ORM nào.
• Application Layer (Use Cases): Điều phối các luồng nghiệp vụ thông qua các interface Repository.
• Infrastructure Layer: Triển khai thực tế các interface (kết nối MongoDB, PostgreSQL, Redis cache, gửi mail).
• Presentation Layer: Tiếp nhận HTTP request, validate dữ liệu đầu vào và trả về JSON chuẩn REST.