Đến nội dung chính
notes.vinhnq.com

Tìm kiếm

Web & APIMid25 phút đọc

REST API: nguyên tắc REST, quy ước thiết kế API và cấu trúc dự án Spring Boot

Ôn 21 thẻ
Trong bài này

Cụm bài Web và REST API: 1. Web và HTTP · 2. Thiết kế REST API và Spring Boot

Bài này đi từ ngữ nghĩa HTTP (method safe, idempotent, status code, xem phần 1) lên tầng thiết kế API. Đọc xong, bạn đặt được URL, phân trang, versioning, format lỗi và cache cho một API production, chọn được giữa REST, gRPC, GraphQL, và chia tầng một dự án Spring Boot. Cuối bài là các bài tập dựng khung pet project.

1. Giới thiệu Spring Boot

Ý chính: Spring Boot không thay Spring mà chạy Spring bên dưới, tự cấu hình theo thư viện có trên classpath, chốt version thư viện và nhúng sẵn web server để chạy bằng java -jar.

1.1. Library và framework

  • Library: code đóng gói sẵn để tái sử dụng. Bạn chủ động gọi nó (Jackson, Guava, Apache Commons).
  • Framework: thư viện cộng với quy tắc bạn phải theo. Khác biệt cốt lõi là Inversion of Control (đảo ngược điều khiển): framework gọi code của bạn. Bạn viết @GetMapping, Spring quyết định khi nào gọi method đó (“Don’t call us, we’ll call you”).

Xem thêm về IoC ở bài IoC và Dependency Injection.

1.2. Spring và Spring Boot

Spring “cổ điển” phải cấu hình nhiều: XML, tự khai báo DispatcherServlet và DataSource, deploy WAR lên Tomcat bên ngoài, tự chọn version thư viện cho tương thích. Spring Boot gỡ phần cực nhọc đó:

  • Cấu hình tự động: có thư viện trên classpath mà bạn chưa tự khai báo bean thì Boot tạo giúp.
  • Hết xung đột dependency: starter gom dependency theo mục đích, BOM chốt version.
  • Server nhúng: java -jar app.jar là chạy.
  • Production-ready: Actuator cho health check, metrics.
Spring Boot bên dưới: cơ chế của từng tính năng
Tính năng Cơ chế thực sự
Cấu hình tự động Các class @AutoConfiguration với @ConditionalOnClass, @ConditionalOnMissingBean… Có thư viện trên classpath và bạn chưa tự khai báo bean thì Boot tạo giúp
Giải quyết xung đột dependency Starter gom dependency theo mục đích, và BOM (Bill of Materials, spring-boot-dependencies) chốt version của hàng trăm thư viện đã được test cùng nhau
Nhúng web server Tomcat (mặc định), Jetty hoặc Undertow chạy bên trong một file JAR thực thi
Production-ready Actuator: health check, metrics, info

Mẹo debug: chạy với --debug để xem condition evaluation report, biết auto-config nào được bật và vì sao. Auto-configuration được tìm và bật thế nào, cùng vòng đời khởi động: Spring Boot từ bên trong.

2. REST

Ý chính: REST là một phong cách kiến trúc, không phải giao thức: hệ thống là các resource có URL, client trao đổi representation (JSON) qua các method HTTP chuẩn. Một API production còn cần thống nhất URL, phân trang, versioning, format lỗi và cache.

2.1. API là gì

API (Application Programming Interface) là hợp đồng giữa hai phần mềm: gọi thế nào (giao thức, địa chỉ), gửi gì, nhận gì, lỗi ra sao. Giống cái điều khiển TV: bạn bấm nút, không cần biết mạch bên trong.

2.2. REST là gì

REST (Representational State Transfer) là phong cách kiến trúc do Roy Fielding mô tả năm 2000. Hệ thống được mô hình hoá thành các resource (dữ liệu hoặc chức năng) có định danh là URL. Client thao tác resource bằng cách trao đổi representation (JSON, XML…) qua một tập thao tác chuẩn. Mục tiêu: đơn giản, nhẹ, dễ mở rộng.

2.3. Sáu ràng buộc của REST

  1. Client-Server: tách giao diện khỏi lưu trữ và xử lý, hai bên phát triển độc lập.
  2. Stateless: mỗi request mang đủ thông tin (token, tham số), server không giữ session của client giữa các request. Nhờ vậy thêm instance sau load balancer mà không cần sticky session (ghim một client vào một instance).
  3. Cacheable: response tự nói nó cache được không và bao lâu, ví dụ Cache-Control: max-age=3600.
  4. Uniform Interface: mọi resource truy cập cùng một kiểu: định danh bằng URI, thao tác qua representation, message tự mô tả (method, content type, status), và HATEOAS (response chứa link tới thao tác tiếp theo).
  5. Layered System: client không biết mình nói chuyện trực tiếp với server hay qua CDN, load balancer, API gateway.
  6. Code on Demand (ràng buộc duy nhất không bắt buộc): server gửi code cho client chạy, ví dụ JavaScript.

“Stateless” nói về trạng thái hội thoại; trạng thái nghiệp vụ vẫn nằm trong database. Stateless cũng không bắt buộc dùng JWT: session lưu ở Redis vẫn scale ngang được. So sánh hai cách và các bẫy của JWT (thu hồi token, refresh token) ở Xác thực: session cookie và JWT.

Phần lớn API gọi là “REST” chỉ đạt level 2 trong Richardson Maturity Model, rất ít API làm HATEOAS. Nói rõ điều này khi phỏng vấn.

Level Đặc điểm
0 Một endpoint, mọi thứ qua POST (kiểu RPC/SOAP)
1 Có nhiều resource (URL riêng)
2 Dùng đúng HTTP method và status code
3 Hypermedia (HATEOAS)

2.4. REST API và cấu trúc URL

REST API là một tập endpoint (URL) áp dụng REST trên HTTP.

https://api.example.com:8443/api/v1/courses?category=java&page=0&size=20#reviews
\___/   \_____________/ \__/\_____________/ \___________________________/ \_____/
scheme      domain      port      path               query                fragment
  • Scheme: giao thức, http hoặc https.
  • Domain (host): tên thay cho IP, DNS phân giải.
  • Port: bỏ trống thì mặc định 80 (http) hoặc 443 (https).
  • Path: đường dẫn tới resource.
  • Query parameter: thông tin bổ sung, không bắt buộc (lọc, sắp xếp, phân trang).

2.5. JSON

JSON là định dạng text cho dữ liệu có cấu trúc (object, array, string, number, boolean, null). Lựa chọn khác: XML, YAML, hoặc binary như Protobuf, Avro. REST API thường khai báo JSON qua Content-Type: application/json và Accept: application/json.

Ngày giờ cũng cần quy ước: thời điểm là chuỗi RFC 3339 ở UTC ("2023-09-25T09:20:52.342Z"), ngày thuần là "2023-10-01", đừng để Jackson trả LocalDate thành mảng [2023,10,1]. Kết quả chạy thật của Jackson với từng cấu hình và bẫy khi đọc OffsetDateTime ở bài Lưu ngày giờ trong PostgreSQL, MySQL và JSON.

2.6. Quy ước đặt URL

  • Danh từ, không dùng động từ: method HTTP đã là động từ. POST /orders, không phải POST /createOrder.
  • Danh từ số nhiều: /users, /users/34. Collection và phần tử chung một gốc.
  • Có version: /api/v1/....
  • kebab-case trên path (slide gọi là “slug-case”): /course-categories. URL có thể phân biệt hoa thường, nên chữ thường và gạch nối an toàn nhất.
  • snake_case cho JSON body: quy ước của khoá học, không phải chuẩn REST. Google và nhiều API Java dùng camelCase, Stripe và GitHub dùng snake_case. Quan trọng là nhất quán toàn hệ thống. Jackson: spring.jackson.property-naming-strategy=SNAKE_CASE.

Hành động không phải CRUD thành resource con: POST /v1/orders/145/cancel. Sort: dùng sort=price,-name, đừng dùng +price.

Bảng ví dụ URL và hai lỗi trong ví dụ sort của slide
Hành động Request
Tạo đơn hàng POST /order-service/v1/orders
Xem chi tiết đơn 145 GET /order-service/v1/orders/145
Chỉ sửa tuổi của user 34 PATCH /user-service/v1/users/34
Vô hiệu hoá user 34 DELETE /user-service/v1/users/34
Danh sách khoá học của giảng viên 7 GET /v1/teachers/7/courses
Hành động không phải CRUD POST /v1/orders/145/cancel hoặc POST /v1/orders/145/cancellation

2.7. Phân trang

Bài REST API nâng cao đi tiếp ở quy mô lớn: điều kiện để cursor đúng và không bị client sửa, deferred join khi buộc dùng OFFSET, whitelist field sort, và định nghĩa chặt safe/idempotent cho từng method.

2.8. Versioning

2.9. Định dạng lỗi thống nhất

Đừng để mỗi controller trả lỗi một kiểu. Chuẩn RFC 9457 Problem Details (thay RFC 7807) định nghĩa body lỗi với Content-Type: application/problem+json:

{
  "type": "https://api.example.com/problems/course-full",
  "title": "Course is full",
  "status": 409,
  "detail": "Course 42 has reached its maximum of 100 students",
  "instance": "/v1/courses/42/enrollments",
  "trace_id": "a1b2c3d4"
}

Spring 6+ có sẵn ProblemDetail và ErrorResponseException:

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(CourseFullException.class)
    ProblemDetail handleCourseFull(CourseFullException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
        pd.setTitle("Course is full");
        pd.setType(URI.create("https://api.example.com/problems/course-full"));
        return pd;
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        pd.setTitle("Validation failed");
        pd.setProperty("errors", ex.getFieldErrors().stream()
                .map(e -> Map.of("field", e.getField(), "message", e.getDefaultMessage()))
                .toList());
        return pd;
    }
}

Không bao giờ trả stack trace hay câu SQL trong response, vì đó là lộ thông tin cho kẻ tấn công. Log chi tiết ở server, trả trace_id để tra cứu.

2.10. Caching với HTTP header

  • Cache-Control: max-age=3600: cache được 3600 giây.
  • no-cache: được lưu nhưng phải hỏi lại server trước khi dùng. no-store: không được lưu (dữ liệu nhạy cảm).
  • private (chỉ trình duyệt) và public (CDN, proxy cũng được). Dữ liệu riêng của user phải private hoặc no-store.
  • ETag + If-None-Match: ETag là “số phiên bản” của response. Server trả ETag: "v7", lần sau client gửi If-None-Match: "v7"; chưa đổi thì server trả 304 Not Modified không body.
  • ETag + If-Match cho ghi: client PUT kèm If-Match: "v7"; nếu người khác đã sửa thành v8, server trả 412 Precondition Failed. Đây là optimistic locking trên HTTP, khớp với @Version trong JPA (xem ORM và JPA).
@GetMapping("/v1/courses/{id}")
ResponseEntity<CourseResponse> get(@PathVariable long id) {
    CourseResponse course = courseService.get(id);
    return ResponseEntity.ok()
            .eTag(String.valueOf(course.version()))
            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(5)).cachePrivate())
            .body(course);
}

3. REST so với SOAP, gRPC, GraphQL

Ý chính: REST cho API công khai và frontend; gRPC cho service nội bộ cần nhanh; GraphQL khi nhiều loại client cần dữ liệu khác nhau; SOAP khi buộc phải tích hợp hệ thống cũ.

  • SOAP: giao thức message XML, chuẩn chặt (WSDL), nặng, khó cache vì mọi thứ là POST.
  • gRPC: RPC trên HTTP/2 với Protobuf (binary), có streaming hai chiều, nhưng trình duyệt cần gRPC-Web/proxy.
  • GraphQL: một endpoint, client tự chọn field, tránh over/under-fetching (lấy thừa/thiếu dữ liệu), nhưng khó cache và dễ dính N+1 ở resolver.
Bảng so sánh đầy đủ REST, SOAP, gRPC, GraphQL
REST SOAP gRPC GraphQL
Bản chất Phong cách kiến trúc trên HTTP Giao thức message XML, có chuẩn chặt (WSDL, WS-Security) RPC trên HTTP/2, Protobuf Ngôn ngữ truy vấn, một endpoint
Định dạng JSON (thường) XML Binary (Protobuf) JSON
Hợp đồng OpenAPI (tuỳ chọn) WSDL (bắt buộc) File .proto (bắt buộc), sinh code Schema có kiểu (bắt buộc)
Hiệu năng Tốt Nặng (XML verbose) Rất tốt, hỗ trợ streaming hai chiều Tốt, nhưng query phức tạp có thể tốn
Cache HTTP Dễ (GET + URL) Khó (mọi thứ là POST) Khó Khó (thường POST một endpoint)
Trình duyệt gọi trực tiếp Có Có nhưng cồng kềnh Cần gRPC-Web/proxy Có
Điểm mạnh Đơn giản, phổ biến, công cụ nhiều Giao dịch doanh nghiệp, ngân hàng, hệ thống cũ Giao tiếp service-to-service nội bộ, latency thấp Client tự chọn field, gom nhiều resource một lần, tránh over/under-fetching
Điểm yếu Over-fetching, nhiều round-trip Phức tạp, nặng Khó debug bằng mắt, phụ thuộc HTTP/2 N+1 ở resolver, khó rate limit và cache, bảo mật query (độ sâu, độ phức tạp)

4. Cấu trúc dự án Spring Boot

Ý chính: chia controller → service → repository, mỗi tầng một việc, và chỉ đưa DTO ra ngoài. Khi dự án lớn, cân nhắc tổ chức theo tính năng và ép quy tắc phụ thuộc bằng công cụ.

4.1. Các tầng

flowchart LR
  C[Client] -->|HTTP + JSON| CT[Controller]
  CT -->|DTO| SV[Service]
  SV -->|Entity| RP[Repository]
  RP -->|SQL| DB[(Database)]
  • Controller: nhận request, validate input, gọi service, trả response. Không chứa logic nghiệp vụ.
  • DTO (Data Transfer Object): object chở dữ liệu giữa các tầng và ra ngoài. Java 17+ dùng record rất gọn.
  • Service: logic nghiệp vụ, ranh giới transaction (@Transactional).
  • Repository: truy vấn và thao tác dữ liệu.
  • Entity: class ánh xạ với bảng.

Không trả thẳng entity vì: lộ field nhạy cảm (password hash), dính lazy loading và vòng lặp khi serialize quan hệ hai chiều, và API bị trói vào schema DB.

4.2. Các package phụ trợ

Ngoài các tầng chính còn model, util, constant, exception, config, filter.

Mỗi package phụ trợ chứa gì
Package Chứa gì
model Class nghiệp vụ không phải entity, không phải DTO: kết quả tính toán, tham số đầu vào cho service
util Hàm tiện ích không trạng thái (xử lý ngày, chuỗi…)
constant Enum, hằng số
exception Exception tuỳ chỉnh và @RestControllerAdvice xử lý lỗi tập trung
config Các @Configuration và bean không thuộc tầng nào (Jackson, CORS, security, client HTTP)
filter Servlet filter: logging request, gắn trace id, xác thực

Bài tập

Các bài tập xoay quanh pet project của khoá học: nền tảng khoá học online (E-Learning). Theo schema của buổi thực hành, hệ thống có học viên (user), giáo viên và admin (hai bảng riêng), khoá học → chương → bài học (loại VIDEO/PDF/DOCX/SLIDE, có thứ tự), lượt đăng ký kèm rating/review, và tiến độ từng bài (START/PROCESSING/DONE). Schema đầy đủ và các truy vấn ở Bài tập SQL trên database E-Learning.

Đừng nhầm: cụm Thực hành backend phân tích hệ thống đặt phòng khách sạn, là ví dụ mẫu của giảng viên về cách đi từ yêu cầu đến thiết kế dữ liệu và API. Dưới đây áp dụng phương pháp đó cho E-Learning.

Bài 1: Khởi tạo project Spring Boot và API “Hello”

Yêu cầu (diễn đạt lại): tạo project Spring Boot cho pet project, đẩy lên Git, và viết một endpoint trả về chuỗi chào mừng của dự án khoá học online.

Lời giải Bài 1: Spring Initializr, HelloController và push lên Git

Tạo project bằng Spring Initializr (Java 21, dependency Spring Web):

curl https://start.spring.io/starter.zip \
  -d type=maven-project -d javaVersion=21 \
  -d groupId=com.vinhnq -d artifactId=elearning \
  -d dependencies=web,validation,actuator \
  -o elearning.zip && unzip elearning.zip -d elearning
package com.vinhnq.elearning.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v1")
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello from the e-learning project";
    }
}
./mvnw spring-boot:run
curl -i http://localhost:8080/api/v1/hello

git init && git add . && git commit -m "Bootstrap the e-learning service"
git remote add origin git@github.com:<user>/elearning.git
git push -u origin main

@RestController = @Controller + @ResponseBody, nên giá trị trả về được ghi thẳng vào response body (String thì text/plain, object thì Jackson chuyển thành JSON). Nhớ kiểm tra .gitignore đã loại target/ và file cấu hình chứa mật khẩu.

Bài 2: Định nghĩa toàn bộ URL của pet project và “echo” input

Yêu cầu (diễn đạt lại): định nghĩa đủ các endpoint REST theo chức năng của pet project. Chưa cần logic: mỗi endpoint trả lại chính body hoặc tham số nhận được, không có thì trả null. Mục đích là chốt hợp đồng API trước khi code nghiệp vụ.

Hai quyết định đáng nhớ: tiến độ và review dùng PUT (idempotent, retry không tạo bản trùng), và các route /me/... lấy học viên từ token thay vì nhận user_id trên URL.

Lời giải Bài 2: bảng endpoint E-Learning và controller echo

Endpoint bám theo các bảng của schema (giáo viên, khoá học, chương, bài học, đăng ký, tiến độ, đánh giá):

Chức năng Endpoint
Tìm kiếm, lọc, phân trang khoá học GET /api/v1/courses?keyword=&teacher_id=&status=ACTIVE&page=0&size=20&sort=created_date:desc
Xem chi tiết GET /api/v1/courses/{course_id}
Tạo khoá học POST /api/v1/courses
Cập nhật toàn bộ PUT /api/v1/courses/{course_id}
Cập nhật một phần PATCH /api/v1/courses/{course_id}
Xoá DELETE /api/v1/courses/{course_id}
Khoá học của một giảng viên GET /api/v1/teachers/{teacher_id}/courses
Học viên đăng ký khoá học POST /api/v1/courses/{course_id}/enrollments
Danh sách chương của khoá (theo thứ tự) GET /api/v1/courses/{course_id}/chapters
Thêm chương POST /api/v1/courses/{course_id}/chapters
Bài học của một chương GET /api/v1/chapters/{chapter_id}/lessons
Thêm bài học (type: VIDEO, PDF, DOCX, SLIDE) POST /api/v1/chapters/{chapter_id}/lessons
Khoá học tôi đã đăng ký, lọc theo tiến độ GET /api/v1/me/enrollments?status=PROCESSING
Cập nhật tiến độ một bài ({"status": "DONE"}) PUT /api/v1/me/courses/{course_id}/lessons/{lesson_id}/progress
Chấm điểm và review khoá đã học ({"rating": 5, "review": "..."}) PUT /api/v1/me/courses/{course_id}/review
Admin khoá tài khoản học viên ({"status": "INACTIVE"}) PATCH /api/v1/users/{user_id}
Quản lý giáo viên (bảng riêng, không phải role) GET/POST /api/v1/teachers, GET/PATCH /api/v1/teachers/{teacher_id}

Tiến độ và review dùng PUT vì mỗi lượt đăng ký chỉ có một bản ghi tiến độ cho mỗi bài và một review. Client gửi trạng thái mong muốn, gửi lại bao nhiêu lần cũng ra cùng kết quả (idempotent), nên app mobile retry khi mạng chập chờn không tạo bản trùng. /me/... lấy học viên từ token, để không ai sửa được tiến độ của người khác bằng cách đổi id.

Ngược lại, POST /api/v1/chapters/{chapter_id}/lessons (thêm bài học) hay một API thanh toán không idempotent: app retry sau khi mất response là tạo thêm một bản ghi. Cách chuẩn là client gửi header Idempotency-Key và server dựa vào một unique constraint để trả lại kết quả lần đầu; cài đặt và chạy thử trên PostgreSQL ở bài Idempotency phần 1.

public record CourseRequest(
        @NotBlank @Size(max = 255) String name,
        @Size(max = 1000) String description,
        @NotNull Long teacherId) {}

public record CourseSearchParams(String keyword, Long teacherId, String status,
                                 Integer page, Integer size, String sort) {}

@RestController
@RequestMapping("/api/v1/courses")
public class CourseController {

    @GetMapping
    public CourseSearchParams search(CourseSearchParams params) {
        return params; // Spring bind query param vào record
    }

    @GetMapping("/{courseId}")
    public Map<String, Object> detail(@PathVariable long courseId) {
        return Map.of("course_id", courseId);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public CourseRequest create(@Valid @RequestBody CourseRequest body) {
        return body;
    }

    @PutMapping("/{courseId}")
    public CourseRequest replace(@PathVariable long courseId, @Valid @RequestBody CourseRequest body) {
        return body;
    }

    @PatchMapping("/{courseId}")
    public Map<String, Object> patch(@PathVariable long courseId, @RequestBody Map<String, Object> changes) {
        return changes;
    }

    @DeleteMapping("/{courseId}")
    public Object delete(@PathVariable long courseId) {
        return null; // không có body: Spring trả 200 rỗng; bản thật nên trả 204
    }
}

Bài 3: Đẩy cấu trúc thư mục rỗng lên Git bằng .gitkeep

Yêu cầu (diễn đạt lại): tạo sẵn các package (controller, dto, service, repository, entity, config…) và đẩy lên Git dù chưa có code.

Lời giải Bài 3: script tạo package và .gitkeep
BASE=src/main/java/com/vinhnq/elearning
for p in controller dto service repository entity model util constant exception config filter; do
  mkdir -p "$BASE/$p" && touch "$BASE/$p/.gitkeep"
done
git add . && git commit -m "Add the package skeleton" && git push

Khi package đã có file Java thật, xoá .gitkeep đi.

Ghi nhớ

  • Giải thích được Spring Boot thêm gì vào Spring, và cách xem auto-config nào được bật.
  • Kể được sáu ràng buộc REST và vì sao “stateless” không có nghĩa là app không có database.
  • Biết khi nào dùng offset, khi nào dùng cursor pagination, và viết được câu SQL keyset.
  • Phân biệt được thay đổi tương thích và breaking change, cùng cách khai tử version cũ.
  • Giải thích được no-cache vs no-store, và ETag dùng cho cả 304 lẫn optimistic locking.

Câu hỏi phỏng vấn

Junior

Vì sao không nên trả entity trực tiếp ra API?

Vì entity là mô hình lưu trữ, không phải hợp đồng API: trả thẳng ra thì lộ dữ liệu và trói client vào schema DB.

Cụ thể: lộ field nhạy cảm, dính lỗi lazy loading hoặc vòng lặp vô hạn khi Jackson serialize quan hệ hai chiều, và mọi thay đổi schema DB đều thành breaking change cho client. DTO tách hợp đồng API khỏi mô hình lưu trữ.

Spring Boot khác Spring Framework thế nào?

Spring Boot không thay thế Spring mà chạy Spring bên dưới với cấu hình mặc định hợp lý.

Nó thêm auto-configuration (tạo bean dựa trên thư viện có trên classpath, chỉ khi bạn chưa tự khai báo), starter cùng BOM để chốt version tương thích, server nhúng để chạy bằng java -jar, và Actuator cho health check, metrics. Bạn vẫn override được mọi mặc định; chạy với --debug để xem auto-config nào được bật và vì sao.

Mid

“Stateless” trong REST nghĩa là gì? App có database thì còn stateless không?

Có. Stateless nói về trạng thái hội thoại: server không giữ session của client giữa các request; trạng thái nghiệp vụ vẫn nằm trong database.

Mỗi request tự mang đủ thông tin (ví dụ JWT). Lợi ích là scale ngang dễ: request nào tới instance nào cũng được, không cần sticky session.

Offset pagination có vấn đề gì và giải pháp?

Trang sâu chậm và dữ liệu thay đổi gây lặp/mất phần tử; giải pháp là keyset (cursor) pagination.

OFFSET n buộc DB đọc rồi bỏ n dòng. Keyset lọc theo giá trị cuối của trang trước (WHERE (created_at, id) < (?, ?)) với index phù hợp, hiệu năng ổn định, nhưng không nhảy được tới trang bất kỳ.

no-cache và no-store khác nhau thế nào? ETag dùng để làm gì?

no-cache cho lưu nhưng phải xác nhận lại với server trước khi dùng; no-store cấm lưu. ETag là phiên bản của representation.

Dùng ETag với If-None-Match để server trả 304 khi chưa đổi, và với If-Match để làm optimistic concurrency control (412 nếu đã bị người khác sửa).

Senior

Bạn sẽ versioning API thế nào và quản lý breaking change ra sao?

Mặc định URI version (/v1), nhưng thứ quan trọng là chính sách tương thích và quy trình khai tử version cũ.

  • URI version rõ ràng, dễ route và cache.
  • Thay đổi cộng thêm (field, endpoint mới) không tăng version, client phải bỏ qua field lạ. Đổi tên, xoá, đổi kiểu hoặc ý nghĩa là breaking, cần version mới.
  • Chạy song song hai version một thời gian, báo bằng Deprecation/Sunset, theo dõi traffic version cũ trước khi tắt.
  • Contract test (OpenAPI diff, consumer-driven contract) trong CI để bắt breaking change sớm.
Khi nào chọn gRPC hoặc GraphQL thay vì REST?

gRPC cho giao tiếp nội bộ cần latency thấp và hợp đồng chặt; GraphQL khi nhiều loại client cần dữ liệu khác nhau. REST vẫn là mặc định cho API công khai.

  • gRPC: payload nhỏ, streaming; đổi lại khó debug và trình duyệt không gọi trực tiếp.
  • GraphQL: giảm round-trip; đổi lại khó cache HTTP, phải chống N+1 ở resolver (DataLoader) và giới hạn độ sâu/độ phức tạp query.
  • REST: đơn giản, cache tốt, công cụ phong phú.
Thiết kế format lỗi cho một hệ thống nhiều service như thế nào?

Dùng chung một chuẩn như RFC 9457 Problem Details, đặt trong thư viện dùng chung hoặc ở API gateway để mọi service nhất quán.

  • Field: type (URI định danh loại lỗi, ổn định để client switch), title, status, detail, instance, cộng mở rộng như errors cho validation và trace_id để tra log.
  • Status code đúng ngữ nghĩa để retry và monitoring hoạt động.
  • Không lộ stack trace, SQL, tên class nội bộ.
Một API GET bị gọi rất nhiều và chậm. Bạn tối ưu theo những hướng nào?

Đo trước (APM, slow query log), rồi tối ưu từ query lên cache, và trả lời được “dữ liệu cũ tối đa bao lâu thì chấp nhận được” cho mỗi lớp cache.

  • Tối ưu query và index, tránh N+1.
  • Cache HTTP (Cache-Control, ETag/304, CDN nếu là dữ liệu công khai).
  • Cache ứng dụng (Caffeine, Redis) với chiến lược invalidation rõ ràng.
  • Giảm payload (phân trang, chọn field, nén gzip/br); bật HTTP/2 keep-alive.
  • Giới hạn tác động bằng rate limit và timeout.

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
stateless /ˈsteɪt.ləs/ không lưu trạng thái phiên “Because the API is stateless, we can add instances behind the load balancer.”
resource /ˈriː.sɔːrs/ tài nguyên “Each resource is identified by a URI.”
representation /ˌrep.rɪ.zenˈteɪ.ʃən/ cách biểu diễn “The client exchanges JSON representations of the resource.”
endpoint /ˈend.pɔɪnt/ điểm cuối API “We expose one endpoint per resource collection.”
backward compatible /ˈbæk.wərd kəmˈpæt.ə.bəl/ tương thích ngược “Adding an optional field is a backward-compatible change.”
breaking change /ˈbreɪ.kɪŋ tʃeɪndʒ/ thay đổi phá vỡ client “Renaming a field is a breaking change, so it needs a new version.”
pagination /ˌpædʒ.əˈneɪ.ʃən/ phân trang “We switched to cursor pagination because deep offsets were slow.”
over-fetching /ˌoʊ.vərˈfetʃ.ɪŋ/ lấy thừa dữ liệu “GraphQL helps avoid over-fetching on mobile clients.”
conditional request /kənˈdɪʃ.ən.əl rɪˈkwest/ request có điều kiện “A conditional request with If-None-Match can return 304.”
contract /ˈkɑːn.trækt/ hợp đồng API “We agree on the API contract before writing business logic.”
auto-configuration /ˌɔː.toʊ kənˌfɪɡ.jəˈreɪ.ʃən/ cấu hình tự động “Spring Boot’s auto-configuration backs off as soon as you define your own bean.”
hypermedia /ˈhaɪ.pɚˌmiː.di.ə/ link trong response “Very few public APIs actually use hypermedia controls.”

Ghi chép dựa trên khoá Fundamentals of Backend (Ronin Engineer), viết lại theo cách hiểu của mình.