Wavi Books · System Design, Backend & Microservices

REST API là gì? Nguyên tắc thiết kế API dễ dùng và dễ bảo trì

Nguyễn Minh Trí · Biên tập chuyên môn Wavi Books

REST API là gì, HTTP method, status code, resource, idempotency, pagination và các nguyên tắc thiết kế API dễ dùng, bảo trì.

## REST API là gì

## Câu trả lời ngắn trước khi đi vào kiến trúc

REST API là gì, HTTP method, status code, resource, idempotency, pagination và các nguyên tắc thiết kế API dễ dùng, bảo trì. Hãy bắt đầu từ yêu cầu, điểm hỏng và hậu quả nghiệp vụ rồi mới chọn thành phần kỹ thuật.

Một hệ thống có thể chạy rất ổn trong buổi demo nhưng bắt đầu lộ vấn đề khi lưu lượng tăng, mạng chập chờn hoặc một dịch vụ phía sau phản hồi chậm. Lúc đó, câu hỏi đáng giá không phải là thêm công nghệ nào cho sơ đồ đẹp hơn, mà là điểm hỏng thật sự nằm ở đâu và người dùng chịu hậu quả gì.

Một API tốt thường không gây chú ý: người dùng tích hợp được ngay, lỗi đọc là hiểu và thay đổi không làm mọi thứ vỡ vụn. Sự đơn giản ấy là kết quả của rất nhiều quyết định có chủ ý.

REST API là cách thiết kế giao diện phần mềm quanh tài nguyên và các thao tác HTTP. Một API tốt có URL dễ hiểu, quy ước nhất quán, lỗi rõ ràng và hành vi có thể dự đoán.

REST không đồng nghĩa với việc ghép động từ vào URL. Developer cần mô hình hóa tài nguyên, chọn method, status code và hợp đồng dữ liệu phù hợp với nghiệp vụ.

## Những khái niệm cốt lõi cần nắm

## API là một cuộc trò chuyện giữa các hệ thống

URL cho biết tài nguyên, HTTP method cho biết hành động và status code cho biết kết quả. Khi ba phần này nhất quán, developer có thể đoán cách dùng endpoint mới mà không phải đọc lại mọi trang tài liệu.

## Chuyện gì xảy ra khi đem vào dự án thật?

API trở nên khó bảo trì khi tên gọi phản ánh cách code bên trong thay vì ngôn ngữ nghiệp vụ. Chỉ một lần đổi database hoặc quy trình xử lý cũng có thể buộc client thay đổi theo.

## Nếu bắt đầu hôm nay, tôi sẽ làm thế này

Hãy thiết kế hợp đồng từ góc nhìn người gọi API. Viết trước vài request, response và trường hợp lỗi; nếu đồng đội đọc mà hiểu được, bạn đã đi đúng hơn một nửa chặng đường.

- GET đọc tài nguyên và không làm thay đổi trạng thái.

- POST tạo hoặc kích hoạt xử lý.

- PUT và DELETE cần xét tính idempotent.

- Pagination, filter và sort kiểm soát tập kết quả.

## Lộ trình thực hành từng bước

- Bước 1: Viết use case và mô hình tài nguyên.

- Bước 2: Định nghĩa OpenAPI cùng ví dụ lỗi.

- Bước 3: Kiểm thử tương thích, phân quyền và giới hạn tốc độ.

## Những sai lầm thường gặp

- Luôn trả HTTP 200 kể cả khi lỗi.

- Thay đổi response mà không quản lý phiên bản.

- Để lộ chi tiết nội bộ trong thông báo lỗi.

## Góc nhìn dành cho người học và developer Việt Nam

Các nhóm backend Việt Nam nên thống nhất quy ước API bằng tài liệu dùng chung và review hợp đồng trước khi frontend, mobile và đối tác tích hợp.

## Nên học tiếp như thế nào?

## Bắt đầu từ tài nguyên và workflow nghiệp vụ

API tốt không sinh ra từ việc đổi tên hàm thành URL. Hãy xác định thực thể, quan hệ và hành động. `/orders/{id}` biểu diễn đơn hàng; việc hủy có thể là PATCH trạng thái hoặc action `/orders/{id}/cancellations` nếu hủy có dữ liệu và vòng đời riêng.

Không phải mọi nghiệp vụ đều CRUD thuần. Thanh toán, xuất báo cáo hoặc duyệt yêu cầu là process. Điều quan trọng là hợp đồng rõ, nhất quán và phản ánh domain thay vì ép mọi thứ vào một mẫu.

## Method, idempotency và retry

GET an toàn và idempotent; PUT, DELETE được kỳ vọng idempotent; POST thường không. Với tạo thanh toán hoặc đơn hàng, client có thể retry khi timeout dù server đã xử lý. Idempotency-Key giúp server nhận biết cùng yêu cầu và trả kết quả trước đó thay vì tạo giao dịch mới.

```http POST /payments HTTP/1.1 Idempotency-Key: order-9821-payment-1 Content-Type: application/json {"order_id": 9821, "amount": 349000, "currency": "VND"} ```

Server cần lưu key, fingerprint request, trạng thái và response trong khoảng thời gian phù hợp. Nếu cùng key nhưng body khác, phải trả lỗi thay vì tái sử dụng mơ hồ.

## Error contract có thể hành động

Status code cho biết lớp lỗi; response cho biết mã nghiệp vụ và chi tiết an toàn. 400 cho request sai, 401 chưa xác thực, 403 không có quyền, 404 không tồn tại, 409 xung đột, 422 không thỏa quy tắc, 429 vượt giới hạn và 5xx cho lỗi server.

```json { "error": { "code": "INSUFFICIENT_STOCK", "message": "Sản phẩm không đủ tồn kho", "details": {"sku": "WV-101", "available": 2}, "request_id": "req_7f91" } } ```

Không trả stack trace, query hoặc secret. Request ID giúp support nối phản hồi người dùng với log server.

## Pagination và filter

Offset pagination đơn giản nhưng chậm và không ổn định khi dữ liệu thay đổi. Cursor pagination dùng khóa sắp xếp như created_at + id, phù hợp feed lớn. API phải quy định sort mặc định, giới hạn page size và cách encode cursor.

Filter cần whitelist field/operator để tránh truy vấn tùy ý. Search toàn văn nên tách khỏi filter chính xác. Với endpoint quan trọng, giới hạn độ phức tạp truy vấn để bảo vệ database.

## Versioning và tương thích

Ưu tiên thay đổi tương thích: thêm field optional, không đổi nghĩa field cũ, client bỏ qua field lạ. Khi bắt buộc phá vỡ, dùng version ở URL/header và công bố deprecation, telemetry client cùng thời hạn migration. Duy trì quá nhiều version làm tăng test và vận hành.

## Bảo mật theo lớp

TLS bảo vệ đường truyền; authentication xác định danh tính; authorization kiểm tra quyền trên từng tài nguyên; input validation ngăn dữ liệu sai; rate limit giảm lạm dụng; audit log ghi hành động nhạy cảm. API key không thay thế user authorization.

Đối với object-level authorization, luôn kiểm tra người dùng có quyền với đúng `order_id` hay không. Chỉ giấu nút trên frontend không phải bảo mật.

## Thiết kế contract-first

Viết OpenAPI, example và error trước khi các client tích hợp. Review với frontend/mobile để phát hiện round trip thừa hoặc field thiếu. Contract test trong CI giúp ngăn response thay đổi ngoài ý muốn.

## Danh sách kiểm tra review API

Tài nguyên và tên nhất quán; method/status đúng; idempotency cho thao tác tiền/đơn; pagination; error code; auth; rate limit; timeout; versioning; log và metric. Sau cùng, thử dùng API như một client mới chỉ có tài liệu—nếu không thể hoàn thành workflow, thiết kế chưa xong.

## Góc nhìn dành cho developer Việt Nam

Với backend developer và kỹ sư phần mềm tại Việt Nam, kiến thức này đặc biệt hữu ích khi làm sản phẩm có thanh toán, đơn hàng, dữ liệu khách hàng hoặc chuẩn bị phỏng vấn System Design. Nhà tuyển dụng thường quan tâm cách bạn giải thích giả định và đánh đổi hơn là số lượng công nghệ bạn nhớ tên.

## Đọc tiếp trên Wavi Books

Nếu bạn muốn học chủ đề này theo một lộ trình có cấu trúc, có thể xem Building Microservices, 2nd Edition bản tiếng Việt tại [Wavi Books](/sach/building-microservices-sam-newman-2026). Sách liên quan được đặt sau phần kiến thức để bạn có thể đánh giá nội dung trước khi chọn mua.