Lesson 3.1: Resource Naming

Thời lượng: 20 phút
Level: Beginner
Yêu cầu: Đã nắm vững HTTP Methods.

Mục tiêu bài học

Sau bài học này, bạn sẽ:

• Biết cách dùng danh từ (Nouns) thay vì động từ (Verbs) trong URL.
• Hiểu quy tắc số nhiều (Pluralization).
• Sử dụng đúng Kebab-case cho URL.

Nội dung chính

1. Nouns, not Verbs

Trong thiết kế REST, URL đại diện cho Tài nguyên (Cái gì), còn HTTP Method đại diện cho Hành động (Làm gì).

Sai (Verb-based):

• POST /createUser
• GET /getOrders
• POST /update_product

Đúng (Noun-based):

• POST /users (Tạo mới)
• GET /orders (Lấy danh sách)
• PATCH /products/1 (Cập nhật sản phẩm 1)

2. Luôn dùng số nhiều (Pluralization)

Có hai trường phái: dùng số ít (/user) và dùng số nhiều (/users). Cộng đồng chuyển dịch sang dùng Số nhiều cho mọi trường hợp để nhất quán.

• GET /users : Lấy danh sách users.
• GET /users/123 : Lấy user có ID 123 trong danh sách users.

Ngoại lệ: Singleton resources (Tài nguyên duy nhất của một context cụ thể).

• GET /profile : Thông tin cá nhân của người đang đăng nhập (không cần ID).
• GET /settings : Cài đặt của hệ thống.

3. Kebab-case cho URL

Để URL dễ đọc và thân thiện với SEO, chúng ta luôn dùng kebab-case (dấu gạch ngang). Tránh dùng camelCase hay snake_case trong URL.

• GET /auction-sessions
• GET /auction_sessions
• GET /auctionSessions

Nguyên tắc then chốt

"URL nên mô tả bản thân dữ liệu, không mô tả quy trình."

Hãy nghĩ về URL như một địa chỉ nhà. Địa chỉ nhà cho biết "nhà nào", còn việc bạn đến đó để giao hàng, sửa nhà hay phá nhà thì do phương thức vận chuyển (HTTP Method) quyết định.

Thực hành

Bài tập 1: Refactor danh sách URL

Hãy sửa các URL sau sang chuẩn REST Design System:

1. POST /api/save-new-comment
2. GET /api/user_settings/1
3. POST /api/deletePost?id=5

Gợi ý:

Tình huống thực tế

Scenario 1: Feature "Chốt đơn"

Bối cảnh: Bạn cần viết API để chuyển trạng thái Order từ "Pending" sang "Completed".

Hướng tiếp cận:

• POST /orders/1/complete (Dùng động từ).
• PATCH /orders/1 với body { "status": "completed" }. (Dùng danh từ và cập nhật trạng thái).

Tuy nhiên, nếu hành động "Chốt đơn" đi kèm với rất nhiều logic nghiệp vụ phức tạp không chỉ là đổi trạng thái, hãy xem bài 3.3: Complex Actions.

Câu hỏi phỏng vấn

Junior/Mid Level

1. Q: Tại sao nên dùng số nhiều cho resource mặc dù chỉ lấy 1 phần tử? A: Để đảm bảo tính nhất quán trên toàn hệ thống. Nó giúp cấu trúc URL trở nên dự đoán được (predictable). Người dùng API luôn biết rằng sau /resources sẽ là /resources/:id.

Tóm tắt

Những điều cần nhớ

• URL = Danh từ.
• Luôn dùng số nhiều.
• Kebab-case cho URL.
• Trả về 404 nếu gọi tới số ít mà không có cơ chế chuyển hướng.

Bước tiếp theo

Bài tiếp theo: Lesson 3.2: Hierarchical Relationships - Cách thiết kế URL khi các tài nguyên lồng nhau (VD: Bình luận của một bài viết).

Tiếp tục →