REST API URI Naming Conventions

1. Resource là gì?

Resource trong REST là một khái niệm trừu tượng đại diện cho một tập hợp các thực thể có thể được đặt tên, như tài liệu, hình ảnh, dịch vụ, v.v.

• Singleton Resources: Đại diện cho một thực thể duy nhất, ví dụ: /customers/{id}
• Collection Resources: Chứa nhiều tài nguyên con, ví dụ: /customers
• Sub-Collection Resources: Tài nguyên nằm trong một bộ sưu tập khác, ví dụ: /customers/{id}/accounts

2. Thực tiễn tốt nhất trong thiết kế URI

2.1. Sử dụng danh từ để đại diện cho tài nguyên

• URI RESTful nên sử dụng danh từ thay vì động từ để đảm bảo tính rõ ràng và dễ hiểu.
• Các loại tài nguyên:
  • Document: Đại diện cho một thực thể cụ thể (số ít). VD: /users/{id}
  • Collection: Chứa nhiều tài nguyên cùng loại. VD: /users
  • Store: Do người dùng quản lý. VD: /users/{id}/playlists

2.2. Đảm bảo tính nhất quán

• Sử dụng dấu gạch chéo / để chỉ mối quan hệ phân cấp: VD: /device-management/managed-devices/{id}/scripts
• Không dùng dấu gạch chéo cuối / vì không có giá trị ngữ nghĩa.
• Sử dụng dấu gạch nối - thay vì gạch dưới _ để tránh nhầm lẫn.
• Dùng chữ thường trong URI để nhất quán và tránh lỗi.
• Không sử dụng phần mở rộng tệp như .xml hay .json.

2.3. Tránh sử dụng động từ trong URI

• URI chỉ nên xác định tài nguyên, không mô tả hành động.

• Sử dụng phương thức HTTP để xác định thao tác:

  • GET /users → Lấy danh sách người dùng
  • POST /users → Tạo người dùng mới
  • PUT /users/{id} → Cập nhật người dùng
  • DELETE /users/{id} → Xóa người dùng

• Nếu cần thực hiện hành động, sử dụng tài nguyên trạng thái:

  • Thay vì: /scripts/{id}/execute
  • Dùng: /scripts/{id}/status với POST và action=execute

2.4. Sử dụng tham số truy vấn để lọc tài nguyên

• Không tạo API mới chỉ để lọc dữ liệu, thay vào đó, sử dụng tham số truy vấn:

  /devices?region=USA&brand=XYZ&sort=installation-date

3. Kết luận

• Tài nguyên RESTful nên được định danh bằng danh từ.
• Tránh đặt động từ trong URI để không biến API REST thành RPC.
• Thực hiện các phương thức CRUD bằng HTTP methods thay vì URI động từ.

---

Source: https://restfulapi.net/resource-naming/