Hướng dẫn API Parameters: Sự khác biệt giữa Query, Path, Body và cách sử dụng đúng

Mở đầu

Khi mới bắt đầu làm lập trình viên, mỗi lần gọi API tôi lại đau đầu với câu hỏi "Tại sao lại báo lỗi?". Điều khó khăn nhất là không biết nên đặt tham số ở đâu. Viết trong URL, đặt trong request body, hay ở chỗ khác...

Lúc đó tôi thường bỏ tất cả vào URL rồi gửi đi. Kết quả đương nhiên là hàng loạt lỗi. Chỉ khi được anh senior nhắc nhở "Em chưa nắm vững cơ bản" thì tôi mới học được sự khác biệt giữa Query, Path, và Body.

Chính sự tiếc nuối lúc đó đã thúc đẩy tôi viết bài này.

Tại sao cần hiểu các loại tham số?

API giống như cuộc trò chuyện giữa con người. Khi truyền đạt điều gì đó, cách thức và phương pháp truyền đạt sẽ ảnh hưởng đến cách đối phương hiểu.

• Query parameter: "Hãy tìm kiếm theo điều kiện này"
• Path parameter: "Tôi muốn tài nguyên cụ thể này"
• Body parameter: "Hãy xử lý dữ liệu này"

Nếu dùng nhầm, server sẽ "không hiểu bạn đang nói gì" và trả về lỗi.

【Thực hành】Phân tích chi tiết 3 loại tham số

Query parameter: Vua của tìm kiếm và lọc dữ liệu

Viết sau dấu ? trong URL.

GET /users?role=admin&page=2&limit=10

Tình huống sử dụng:

• Phân trang (page, limit)
• Điều kiện tìm kiếm (keyword, category)
• Sắp xếp (sort, order)

Ưu điểm: Nhìn URL là biết đang làm gì Nhược điểm: Quá dài sẽ làm URL xấu

Path parameter: Chiêu thức chỉ định "người này"

Được nhúng như một phần của URL.

DELETE https://api.example.com/posts/:postId/comments/:commentId

Khi nhập URL trên vào thanh địa chỉ, bảng Path Variables sẽ tự động hiển thị bên dưới. Thiết lập như sau:

• postId = 456
• commentId = 789

Tình huống sử dụng:

• Lấy thông tin người dùng cụ thể
• Xóa bài viết cụ thể
• Định danh duy nhất tài nguyên

Lưu ý: Nhập sai sẽ gặp lỗi 404

Body parameter: Người vận chuyển dữ liệu lớn

Gửi trong request body dưới dạng JSON hoặc XML.

POST /api/users
{
  "name": "Nguyễn Văn A",
  "email": "nguyenvana@example.com",
  "department": "Phòng phát triển",
  "skills": ["JavaScript", "Python", "Go"]
}

Tình huống sử dụng:

• Đăng ký/cập nhật người dùng
• Upload file
• Truyền cấu trúc dữ liệu phức tạp

Những lỗi thường gặp trong thực tế phát triển

Ví dụ sai thường gặp

# Sai: Nhét tất cả dữ liệu Body vào Query
GET /api/users?name=Nguyễn Văn A&email=nguyenvana@example.com&department=Phòng phát triển&skills=JavaScript,Python,Go

# Sai: Dùng Path parameter để lọc
GET /api/users/admin/page2/limit10

Cách phân biệt đúng

# Đúng: Đúng chỗ đúng việc
GET /api/users?role=admin&page=2    # Điều kiện tìm kiếm dùng Query
GET /api/users/123                  # Tài nguyên cụ thể dùng Path
POST /api/users                     # Dữ liệu tạo mới dùng Body

Lựa chọn công cụ nâng cao hiệu quả phát triển

Postman vs Apidog: Cách sử dụng trong thực tế

Trường hợp Postman:

• Tab Params → Query parameter & Path parameter
• Tab Body → Body parameter

Trường hợp Apidog:

• Tab Params → Query parameter & Path parameter
• Tab Body → Body parameter

Cả hai đều có cấu trúc cơ bản giống nhau, nhưng Apidog có thiết kế UI trực quan hơn cho người mới bắt đầu.

Điều tôi đặc biệt thích là tính năng tự động tạo tài liệu. Tiết kiệm công sức tạo spec API thủ công, và thực sự hữu ích trong phát triển nhóm. Cảm giác như lỗi thiết lập tham số cũng giảm đi.

Quy tắc vàng chọn tham số

Tiêu chí phán đoán khi phân vân:

1. "Điều kiện tìm kiếm" → Query
2. "Tài nguyên nào" → Path
3. "Dữ liệu gửi đi" → Body

Kết luận

Không cần phải lo lắng về việc phân biệt tham số như thời mới học nữa. Hiểu được đặc tính của Query, Path, Body sẽ giúp giao tiếp với API trở nên mượt mà.

Đặc biệt gần đây có những công cụ trực quan như Apidog ra đời. Nhờ sự tiến bộ của công nghệ, nỗi lo "không biết viết ở đâu" đã giảm đi rất nhiều so với trước.

Nhưng hiểu biết cơ bản vẫn là điều cần thiết. Không nên phụ thuộc hoàn toàn vào công cụ, mà phải hiểu tại sao đặt tham số ở đó, chỉ khi đó mới thực sự làm chủ được API.

Nếu bài viết này hữu ích, hãy chia sẻ nhé! Có thể có những đồng nghiệp đang gặp khó khăn tương tự. Ngoài ra, nếu bạn có kinh nghiệm hay công cụ nào đó muốn giới thiệu, hãy comment cho tôi biết.