Backend API Engineering for AI Engineers
Trang chủ / Module 1
🔌 Module 1 / 14 · 1 tuần

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.

RESTHTTPResource Modeling
📌 Vì sao module này quan trọng

"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 /getOrdersGET /orders
POST /createOrderPOST /orders
POST /updateOrderStatusPATCH /orders/{id}
POST /deleteOrderDELETE /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ĩaIdempotent?
GETĐọc resource, không thay đổi trạng tháiCó
POSTTạo resource mới (hoặc hành động không idempotent)Không
PUTThay thế toàn bộ resourceCó
PATCHCập nhật một phần resourceKhông đảm bảo (tuỳ cách implement)
DELETEXoá resourceCó

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 CodeKhi nào dùng
200 OKThành công, có trả về nội dung
201 CreatedTạo resource thành công — kèm header Location trỏ tới resource mới
204 No ContentThành công, không có nội dung trả về (thường cho DELETE)
400 Bad RequestClient gửi dữ liệu sai định dạng/thiếu trường bắt buộc
401 UnauthorizedChư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 FoundResource không tồn tại
409 ConflictXung độ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 RequestsVượt rate limit
500 Internal Server ErrorLỗ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
01 endpoint duy nhất, luôn POST, hành động nằm trong body (SOAP-style, RPC thuần)
1Có nhiều resource/URL riêng biệt, nhưng vẫn chỉ dùng 1-2 HTTP method (thường toàn POST)
2Dù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

Thiết kế lại 1 API RPC-style thành REST Level 2

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

✅ 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