REST API: quy tắc đặt tên endpoint chuẩn và dễ dùng

URL của REST API là hợp đồng giao tiếp lâu dài với client. Đặt tên nhất quán ngay từ đầu giúp API dễ đoán, dễ dùng và đỡ phải phá vỡ tương thích về sau.

Dùng danh từ, số nhiều

• Tốt: GET /users, GET /users/42, GET /users/42/orders
• Tránh: GET /getUser?id=42, POST /createUser — động từ đã nằm ở HTTP method rồi

HTTP method mang ý nghĩa hành động

• GET đọc (không đổi dữ liệu)
• POST tạo mới
• PUT thay thế toàn bộ, PATCH sửa một phần
• DELETE xoá

Phân cấp và lọc

Quan hệ cha–con thể hiện qua đường dẫn: /users/42/orders. Lọc, sắp xếp, phân trang dùng query string: /orders?status=paid&sort=-createdAt&page=2.

Vài nguyên tắc khác

1. Chữ thường, dùng gạch ngang cho từ ghép: /order-items
2. Nhất quán số nhiều toàn API — đừng lẫn /user và /orders
3. Đưa phiên bản vào đường dẫn hoặc header: /v1/users
4. Action không map gọn vào CRUD thì dùng sub-resource: POST /orders/42/cancel

👉 Dùng thử công cụ liên quan trên dev-hub: JSON Formatter — chạy hoàn toàn trong trình duyệt, không gửi dữ liệu lên server.