Login

Nguyên tắc thiết kế REST API: tài nguyên, phương thức và đặt tên

  • author-image

    Nguyễn Đình Cường

  • blog-tag
  • blog-comment 0 comment
  • created-date 09 Nov, 2026
blog-thumbnail

Hai lập trình viên cùng làm API có thể tạo ra hai kiểu hoàn toàn khác nhau: một bên gọn gàng dễ đoán, một bên đủ thứ /getUser, /doDelete. Thiết kế REST giúp API nhất quán để người dùng nó đoán trước được hành vi. Dưới đây là những nguyên tắc thực dụng nhất.

Nghĩ theo tài nguyên, không theo hành động

Trong REST, URL đại diện cho tài nguyên (danh từ), còn hành động được thể hiện bằng phương thức HTTP. So sánh:

  • Không nên: POST /createUser, GET /getAllOrders, POST /deleteOrder?id=5
  • Nên: POST /users, GET /orders, DELETE /orders/5

Dùng danh từ số nhiều, chữ thường, phân cách bằng dấu gạch ngang nếu nhiều từ (/order-items), và nhất quán trong toàn hệ thống.

Bốn phương thức quen thuộc

Phương thứcÝ nghĩaVí dụ
GETĐọc dữ liệu, không thay đổi gìGET /users/12
POSTTạo mớiPOST /users
PUTThay thế toàn bộ tài nguyênPUT /users/12
PATCHCập nhật một phầnPATCH /users/12
DELETEXóaDELETE /users/12

Hai khái niệm đáng nhớ: an toàn (GET không được làm thay đổi dữ liệu) và idempotent (gọi nhiều lần cho cùng kết quả như gọi một lần; GET, PUT, DELETE là idempotent, còn POST thì không). Điều này quan trọng khi client thử lại do mạng chập chờn.

Quan hệ giữa các tài nguyên

Dùng lồng nhau khi có quan hệ sở hữu rõ ràng, nhưng đừng lồng quá hai cấp:

GET  /users/12/orders        # đơn hàng của người dùng 12GET  /orders/77              # truy cập trực tiếp một đơn hàngPOST /users/12/orders        # tạo đơn hàng cho người dùng 12

Với hành động không khớp CRUD, bạn có thể mô hình hóa thành tài nguyên con hoặc dùng động từ khi bất khả kháng, ví dụ POST /orders/77/cancel. Thực dụng quan trọng hơn thuần túy.

Lọc, sắp xếp, tìm kiếm qua query string

GET /products?category=books&min_price=50000&sort=-created_at&page=2&per_page=20

Giữ đường dẫn cho định danh tài nguyên, còn các điều kiện tùy chọn đặt ở query string. Quy ước dấu trừ trước tên trường để sắp xếp giảm dần là phổ biến nhưng bạn có thể chọn khác, miễn là nhất quán và có tài liệu.

Định dạng phản hồi nhất quán

Hãy chọn một cấu trúc cho thành công và một cho lỗi, rồi dùng xuyên suốt:

// Thành công{ "data": { "id": 12, "name": "An" } }// Lỗi{ "error": { "code": "validation_failed", "message": "Email không hợp lệ", "fields": { "email": ["không đúng định dạng"] } } }

Một mã lỗi dạng chuỗi ổn định (như validation_failed) giúp ứng dụng khách xử lý logic mà không phải đọc thông điệp văn bản, vốn có thể thay đổi hoặc dịch sang ngôn ngữ khác.

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

  • Dùng GET để thay đổi dữ liệu, dễ bị trình thu thập hoặc cache gọi nhầm.
  • Luôn trả 200 kể cả khi lỗi, buộc client phải đọc nội dung mới biết thành công hay không.
  • Đặt tên không nhất quán: chỗ user_id, chỗ userId.
  • Lộ cấu trúc database ra ngoài thay vì thiết kế theo nhu cầu của người dùng API.
  • Không có phân trang, để một request có thể trả về cả triệu bản ghi.

Tài liệu và ví dụ

Một API tốt đi kèm tài liệu đủ để người khác dùng mà không phải hỏi bạn. Mô tả từng endpoint, tham số, ví dụ yêu cầu và phản hồi, các mã lỗi có thể gặp. Dùng đặc tả OpenAPI để tài liệu có thể được sinh và kiểm thử tự động.

Ví dụ: thiết kế API cho một blog

Hãy áp dụng ngay. Với một blog, các tài nguyên chính là bài viết, bình luận và người dùng. Danh sách endpoint hợp lý có thể là: GET /posts lấy danh sách, POST /posts tạo bài, GET /posts/{id} xem một bài, PATCH /posts/{id} sửa, DELETE /posts/{id} xóa, và GET /posts/{id}/comments cùng POST /posts/{id}/comments cho bình luận. Chỉ mười dòng như vậy đã mô tả gần như toàn bộ hệ thống, và bất kỳ ai nhìn vào cũng đoán được cách dùng mà không cần đọc tài liệu.

Khi nhóm đã đồng ý về danh sách này, việc triển khai ở bất kỳ ngôn ngữ nào cũng trở nên rõ ràng, và nhóm làm giao diện có thể bắt đầu song song với dữ liệu giả. Đó là lợi ích thực tế nhất của việc thiết kế API trước khi viết code.

Kết luận

REST không phải bộ luật cứng nhắc mà là tập quy ước giúp API dễ đoán. Hãy nhất quán, dùng đúng phương thức và mã trạng thái, thiết kế từ góc nhìn người dùng API. Trước khi viết code, thử phác thảo danh sách endpoint ra giấy; bạn sẽ phát hiện nhiều vấn đề thiết kế sớm.

Muốn học bài bản và có lộ trình rõ ràng? Bạn có thể xem các khóa học trên codebem.com.

author_photo
Nguyễn Đình Cường

0 comment