REST API Design Fundamentals
Mô hình hoá resource đúng cách, dùng đúng HTTP method/status code, và Richardson Maturity Model để tự chấm điểm API của bạn.
"API tôi viết cũng dùng HTTP, cũng trả JSON — vậy nó là REST" là hiểu lầm rất phổ biến. Phần lớn API gắn mác "RESTful" thực chất chỉ là RPC-over-HTTP (một loạt endpoint dạng /getUser, /updateOrder) — vẫn hoạt động, nhưng đánh mất toàn bộ lợi ích của REST thật: khả năng đoán được URL, dùng đúng HTTP semantics để cache và debug dễ dàng hơn, và một hợp đồng nhất quán giữa hàng chục service. Module này xây nền tư duy đúng trước khi bàn đến GraphQL hay bất kỳ pattern nâng cao nào.
🎯 Mục tiêu học tập
- Mô hình hoá resource đúng cách (danh từ, không phải hành động) cho một bài toán nghiệp vụ thực tế
- Dùng đúng HTTP method (GET/POST/PUT/PATCH/DELETE) và status code theo đúng ngữ nghĩa chuẩn
- Đánh giá độ trưởng thành của 1 API theo Richardson Maturity Model
- Thiết kế URI nhất quán, dễ đoán, tuân theo quy ước chung của ngành
Resource là danh từ, không phải hành động
Nguyên tắc cốt lõi của REST: URL đại diện cho resource (danh từ — /orders,
/users/42), còn hành động lên resource đó thể hiện qua HTTP method, không
phải qua tên endpoint.
| Sai (RPC-style) | Đúng (REST) |
|---|---|
POST /getOrders | GET /orders |
POST /createOrder | POST /orders |
POST /updateOrderStatus | PATCH /orders/{id} |
POST /deleteOrder | DELETE /orders/{id} |
Quan hệ lồng nhau thể hiện qua đường dẫn: GET /customers/42/orders (đơn hàng của khách hàng
42). Tránh lồng quá 2 cấp — thay vào đó dùng query parameter hoặc endpoint riêng có filter.
HTTP Method & Status Code đúng ngữ nghĩa
| Method | Ý nghĩa | Idempotent? |
|---|---|---|
| GET | Đọc resource, không thay đổi trạng thái | Có |
| POST | Tạo resource mới (hoặc hành động không idempotent) | Không |
| PUT | Thay thế toàn bộ resource | Có |
| PATCH | Cập nhật một phần resource | Không đảm bảo (tuỳ cách implement) |
| DELETE | Xoá resource | Có |
Idempotent nghĩa là gọi lại nhiều lần cho cùng kết quả như gọi 1 lần — tính chất quan trọng để client an toàn retry khi mất kết nối mà không sợ tạo trùng dữ liệu.
| Status Code | Khi nào dùng |
|---|---|
| 200 OK | Thành công, có trả về nội dung |
| 201 Created | Tạo resource thành công — kèm header Location trỏ tới resource mới |
| 204 No Content | Thành công, không có nội dung trả về (thường cho DELETE) |
| 400 Bad Request | Client gửi dữ liệu sai định dạng/thiếu trường bắt buộc |
| 401 Unauthorized | Chưa xác thực (thiếu/sai token) — thực ra nên gọi là "Unauthenticated" |
| 403 Forbidden | Đã xác thực nhưng không có quyền truy cập resource này |
| 404 Not Found | Resource không tồn tại |
| 409 Conflict | Xung đột trạng thái (ví dụ update dựa trên version cũ) |
| 422 Unprocessable Entity | Đúng định dạng nhưng sai logic nghiệp vụ (ví dụ số âm cho số lượng) |
| 429 Too Many Requests | Vượt rate limit |
| 500 Internal Server Error | Lỗi phía server, không phải lỗi của client |
Lỗi phổ biến nhất: trả 200 OK kèm body {"error": "..."} cho mọi tình
huống, kể cả lỗi — buộc client phải parse body để biết có lỗi hay không thay vì dựa vào status code chuẩn
mà mọi HTTP client/proxy/monitoring tool đều hiểu sẵn.
Richardson Maturity Model — tự chấm điểm API của bạn
| Level | Đặc điểm |
|---|---|
| 0 | 1 endpoint duy nhất, luôn POST, hành động nằm trong body (SOAP-style, RPC thuần) |
| 1 | Có nhiều resource/URL riêng biệt, nhưng vẫn chỉ dùng 1-2 HTTP method (thường toàn POST) |
| 2 | Dùng đúng HTTP method và status code theo ngữ nghĩa chuẩn — đây là mức hầu hết API "RESTful" tốt đạt tới, và là mục tiêu thực dụng cho phần lớn hệ thống |
| 3 (HATEOAS) | Response chứa link điều hướng tới các hành động tiếp theo có thể thực hiện — lý thuyết đẹp nhưng hiếm khi triển khai đầy đủ trong thực tế vì độ phức tạp client không tương xứng với lợi ích |
Mục tiêu thực dụng: đạt Level 2 một cách nhất quán trên toàn bộ API — đây đã là bước nhảy lớn so với phần lớn API "REST" thực tế đang ở Level 1.
🏋️ Bài tập thực hành
Cho danh sách endpoint RPC-style: POST /getUserOrders, POST /createNewOrder, POST /cancelOrder, POST /updateOrderAddress, POST /getOrderById, POST /markOrderAsPaid. Thiết kế lại toàn bộ thành REST đúng chuẩn Level 2: đúng resource URL, đúng HTTP method, đúng status code cho từng trường hợp thành công lẫn thất bại (order không tồn tại, order đã bị huỷ không thể cập nhật địa chỉ, v.v). Viết ra bảng ánh xạ đầy đủ.
📚 Tài nguyên học tập
-
MDN — HTTP Request MethodsTài liệu chuẩn về ngữ nghĩa từng HTTP methodDocs
-
MDN — HTTP Response Status CodesDanh sách đầy đủ status code và khi nào dùngDocs
-
Martin Fowler — Richardson Maturity ModelBài viết kinh điển giải thích mô hình trưởng thành RESTBài viết
✅ Tự đánh giá hoàn thành
- Mô hình hoá được resource dạng danh từ cho 1 bài toán nghiệp vụ có quan hệ lồng nhau
- Chọn đúng HTTP method và status code cho ít nhất 8 tình huống khác nhau
- Giải thích được tính chất idempotent và vì sao nó quan trọng cho retry an toàn
- Tự chấm điểm được 1 API có sẵn theo đúng 3 mức của Richardson Maturity Model