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ì

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

- 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?

Sau khi nắm phần cốt lõi, bạn nên tự xây một dự án nhỏ, ghi lại giả định, tiêu chí đánh giá và giới hạn của giải pháp. Các sách liên quan được Wavi Books gợi ý trong bài giúp bạn đào sâu kiến thức theo lộ trình có hệ thống thay vì chỉ ghép các hướng dẫn rời rạc.

## 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.

## Checklist 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.