Thiết kế Resource & URI

Danh từ, không phải động từ

URI đại diện cho một resource (thứ/đối tượng), không phải một hành động. Hành động đã được biểu đạt qua HTTP method rồi, nên không cần lặp lại trong URL.

Sai (dùng động từ)	Đúng (dùng danh từ + HTTP method)
POST /createUser	POST /users
GET /getUserById?id=123	GET /users/123
POST /deleteUser/123	DELETE /users/123

Số nhiều nhất quán

Dùng số nhiều cho tên resource, kể cả khi thao tác trên 1 item cụ thể — giữ ngữ pháp URL nhất quán giữa collection và single item. Đây là quy ước phổ biến nhất hiện nay (Stripe, GitHub, Twilio đều theo cách này).

• Collection: GET /users
• 1 item cụ thể: GET /users/123 (vẫn users, không đổi thành user)

Quy ước viết URL

• Chỉ dùng chữ thường.
• Dùng kebab-case cho từ ghép (/order-items), không dùng snake_case hay khoảng trắng.
• Lồng tối đa 1 cấp (/customers/123/orders) để thể hiện quan hệ sở hữu (orders thuộc về customer nào). Nếu cần đi sâu hơn (ví dụ chi tiết 1 order cụ thể), trỏ thẳng về resource cấp cao nhất (/orders/456) thay vì lồng tiếp (/customers/123/orders/456/items) — lồng quá sâu làm URL khó đọc và khó thay đổi cấu trúc sau này.

Versioning — chọn 1 chiến lược, giữ nhất quán

Chiến lược	Ví dụ	Ghi chú
URI path versioning	/v1/users, /v2/users	Rõ ràng nhất, dễ thấy version ngay trên URL — cách phổ biến nhất
Header-based versioning	Accept: application/vnd.example.v1+json	URL sạch hơn (không lộ version), nhưng khó test/debug bằng mắt thường hơn (không thấy version khi nhìn URL)

Điều quan trọng nhất không phải là chọn cách nào, mà là chọn 1 cách và áp dụng nhất quán cho toàn bộ API — trộn lẫn nhiều kiểu versioning trong cùng hệ thống là nguồn gây nhầm lẫn lớn cho consumer.