Path Parameter

Path Parameter là gì?

Path Parameter là phần biến trong đường dẫn URL dùng để xác định tài nguyên cụ thể trong API. Nó được đặt trong URL path, thường ký hiệu bằng dấu ngoặc nhọn như /users/{userId}, nơi {userId} là placeholder cho giá trị thực tế. Khác với query parameter, Path Parameter là bắt buộc và giúp tạo URL rõ ràng, dễ đọc cho việc truy xuất tài nguyên duy nhất.

Vai trò của Path Parameter trong tích hợp hệ thống

Path Parameter đóng vai trò định danh tài nguyên chính trong RESTful API, giúp server xác định chính xác object cần xử lý. Trong workflow automation, nó được dùng để gọi API endpoint cụ thể, như lấy thông tin user từ /users/123 thay vì query chung chung. Điều này đảm bảo tích hợp hệ thống chính xác, hỗ trợ các công cụ như n8n hoặc Zapier map dữ liệu động vào đường dẫn.

Path Parameter hoạt động như thế nào trong thực tế?

Path Parameter được khai báo trong route definition và tự động capture giá trị từ URL khi request đến. Ví dụ, với endpoint GET /items/{item_id}, server nhận item_id làm tham số hàm, như trong FastAPI: item_id: int để validate kiểu dữ liệu.

Các framework phổ biến xử lý như sau:

• Express.js: Sử dụng req.params.item_id từ route /items/:item_id.
• Spring MVC: @PathVariable int userId từ /user/{userId}.
• FastAPI: item_id: str tự động bind từ path.

Trong OpenAPI spec, khai báo in: path và required: true để mô tả schema. Nếu path chứa sub-path như file, dùng converter :path trong FastAPI: /files/{file_path:path}.

Những lưu ý quan trọng về Path Parameter

Path Parameter phải bắt buộc và dùng cho identity, không dùng cho filter hoặc optional data – dành cho Query Parameter. Bỏ qua nó dẫn đến lỗi 404 Not Found hoặc 400 Bad Request tùy server.

Một số lưu ý thực tế:

• Validate kiểu dữ liệu sớm (int, str, enum) để tránh lỗi runtime.
• Encode đặc biệt ký tự trong giá trị (như / thành %2F) theo RFC 3986.
• Không nhầm với Query Parameter (?key=value) hoặc Header (như Authorization).
• Trong workflow, dùng expression như {{ $json.id }} để inject động vào path.

Lỗi phổ biến là dùng Path Parameter cho sorting/pagination, làm URL dài và không cache tốt.

Các thuật ngữ liên quan đến Path Parameter

Dưới đây là một số thuật ngữ thường liên quan trực tiếp đến Path Parameter trong API và workflow:

• Query Parameter: Tham số tùy chọn ở cuối URL dạng ?key=value, dùng cho filter hoặc pagination.
• Path Variable: Tên gọi khác của Path Parameter trong một số framework như Spring MVC.
• RESTful API: Kiến trúc dùng Path Parameter để định danh tài nguyên theo thứ tự phân cấp.
• OpenAPI: Spec mô tả Path Parameter với in: path cho tài liệu và client generation.

Các câu hỏi thường gặp

Path Parameter khác Query Parameter như thế nào?

Path Parameter dùng cho định danh tài nguyên bắt buộc trong path (như /users/123), còn Query Parameter là tùy chọn cho filter (/users?age=25). Path tạo URL sạch, dễ bookmark; query phù hợp dữ liệu phức tạp hoặc nhiều giá trị.

Khi nào nên dùng Path Parameter trong workflow?

Dùng khi cần truy xuất tài nguyên cụ thể, như lấy order từ /orders/{{orderId}} trong n8n node HTTP Request. Tránh dùng cho search hoặc list để giữ endpoint đơn giản.

Làm gì nếu Path Parameter gây lỗi 404?

Kiểm tra giá trị inject đúng, encode URI, và route match chính xác (bao gồm trailing slash). Thêm logging req.params để debug trong server-side.

Có thể dùng Path Parameter cho file path không?

Có, dùng converter như {file_path:path} trong FastAPI để match sub-path như /files/home/user/file.txt. Điều này linh hoạt cho nested resource nhưng cần validate cẩn thận.