Cách Đặt Tên API “Chuẩn RESTful” Dành Cho Lập Trình Viên Backend

🕒 Đăng ngày: 23/10/2025 |   Lượt xem: 71

Việc đặt tên API nghe có vẻ đơn giản, nhưng nếu không tuân theo chuẩn RESTful thì hệ thống của bạn sẽ nhanh chóng trở nên rối rắm, khó mở rộng và khó hiểu cho người khác.
Bài viết này chia sẻ 6 nguyên tắc vàng giúp bạn đặt tên API rõ ràng, nhất quán và chuyên nghiệp — đúng chuẩn REST quốc tế.

1. Dùng danh từ số nhiều (Plural Nouns)

Trong RESTful API, mỗi endpoint đại diện cho một tài nguyên (resource). Tài nguyên thường là tập hợp dữ liệu, vì vậy bạn nên dùng danh từ số nhiều.

✅ Ví dụ đúng:
GET /products
GET /users
GET /orders
GET /books

❌ Ví dụ sai:
GET /product
GET /user

Điều này giúp API dễ hiểu và nhất quán với quy ước toàn cầu.

2. Dùng HTTP Method thay vì động từ trong URL

Các hành động như lấy, thêm, sửa, xóa đã được thể hiện qua HTTP Method (GET, POST, PUT, PATCH, DELETE).
Không nên chèn thêm các động từ vào đường dẫn.

✅ Đúng:
GET /products        → Lấy danh sách sản phẩm
POST /products       → Thêm sản phẩm mới
GET /products/{id}   → Lấy chi tiết sản phẩm
PUT /products/{id}   → Cập nhật toàn bộ sản phẩm
PATCH /products/{id} → Cập nhật một phần
DELETE /products/{id}→ Xóa sản phẩm

❌ Sai:
GET /getProducts
POST /addProduct
DELETE /removeProduct

HTTP Method đã nói lên hành động, nên URL chỉ cần mô tả tài nguyên mà thôi.

3. Giữ đường dẫn ở dạng chữ thường (lowercase)

URL trong hệ thống phân biệt chữ hoa và chữ thường, vì thế nên giữ mọi endpoint ở dạng lowercase để tránh lỗi không đáng có.

✅ Đúng:
GET /products
GET /users
❌ Sai:
GET /Products
GET /USERS

4. Dùng dấu gạch ngang (-) thay vì gạch dưới (_)

Dấu gạch ngang giúp dễ đọc, dễ hiểu hơn và được khuyến nghị trong chuẩn RFC 3986.

✅ Đúng:
GET /account-settings
❌ Sai:
GET /account_settings
GET /accountsettings

5. Dùng cấu trúc phân cấp (Nested Resources) khi cần

Khi tài nguyên có mối quan hệ cha – con, bạn nên thể hiện điều đó trong URL để rõ ràng hơn.

✅ Đúng:
GET /categories/1/products
GET /posts/123/comments
❌ Sai:
GET /getProductsByCategory?categoryId=1

Nhờ cách này, người đọc chỉ nhìn endpoint cũng hiểu được cấu trúc dữ liệu của hệ thống.

6. Tên tài nguyên rõ ràng, nhất quán và có ý nghĩa

Một API “đẹp” là API mà chỉ cần nhìn vào đã hiểu được mục đích.

✅ Ví dụ chuẩn:
/users
/users/{id}
/users/{id}/orders
/orders/{id}/items

Giữ cách đặt tên nhất quán xuyên suốt dự án sẽ giúp bạn dễ mở rộng, dễ debug và dễ viết tài liệu API sau này.