[FastAPI] 쿼리 파라미터 vs path 파라미터 설계 전략

서론

🔍 FastAPI에서 쿼리 파라미터 vs path 파라미터 – 언제 어떤 걸 쓸까?

FastAPI에서 API를 설계할 때, 이런 고민이 자주 생긴다:

• 어떤 값은 path param으로 받을까?
• 어떤 값은 query param으로 받을까?

예를 들어 /products/{id}와 /products?category=전자제품은 어떤 차이가 있을까?

실무에서는 이걸 기준 없이 섞어 쓰면 유지보수가 어려워진다.

이번 글에서는 그 차이와 설계 기준을 정리한다.

---

🔗 엮인글

[🚀 Dev/Python] - [FastAPI] Swagger UI에서 POST 요청 시 JSON 입력창으로 바뀌는 이유

[🚀 Dev/Python] - [FastAPI] DELETE 요청 시 JSON이 아닌 Path Param으로 값 전달하는 방법

[🚀 Dev/Python] - [FastAPI] DELETE 요청 시 path param 여러 개 받는 방법

[🚀 Dev/Python] - [FastAPI] 다중 필터 검색 API 설계 (예: /products?brand=..&category=..)

[🚀 Dev/Python] - [FastAPI] 페이징, 정렬, 리스트 파라미터까지 포함한 검색 API 확장 설계

[🚀 Dev/Nextjs] - [Nextjs] 필터 UI → FastAPI 다중 필터 API 연결 가이드

---

본론

용도에 따른 정리

구분	Path Parameter	Query Parameter
목적	리소스를 고유하게 식별	리소스를 필터링 / 옵션화
예시	/products/123	/products?category=전자제품
특징	필수 값	선택적 또는 다중 조합 가능
Swagger UI 표현	URL 경로 안에 있음	URL 뒤에 ?로 표시
적절한 경우	단일 항목 조회, 삭제, 수정 등	목록 검색, 정렬, 필터링 등

---

1. 실전 예제 비교

1.1 제품 상세 조회 (path param 사용)

@router.get("/products/{product_id}")
def get_product(product_id: int):
    ...

GET /products/42

→ 고유 리소스를 직접 지정 → path param 적합

---

1.2 제품 목록 필터링 (query param 사용)

@router.get("/products")
def list_products(
    category: Optional[str] = None,
    brand: Optional[str] = None,
    sort_by: Optional[str] = "created_at"
):
    ...

GET /products?category=전자제품&brand=삼성

→ 조합 가능한 필터들 → query param 적합

---

2. 설계 기준 체크리스트

✅ 아래 기준으로 어떤 파라미터를 어디에 넣을지 정리해보자.

 

항목	path param?	query param?
고유 리소스 ID, slug	✅	❌
필터링 조건 (브랜드, 카테고리 등)	❌	✅
정렬 기준, 페이지 번호	❌	✅
선택적 옵션 (예: ?preview=true)	❌	✅
특정 리소스의 하위 리소스	✅ /users/1/posts	❌

---

❗ 혼합 사용 시 주의사항

FastAPI는 path → query 순서로 매칭하므로

path param을 너무 일반화하면 query param과 충돌 가능성이 있음.

예:

@router.get("/{param}")

→ 이런 라우터는 가능하면 지양하고, 고정된 의미 있는 경로 사용을 권장

---

 결론

• path param: 필수 리소스 식별자
• query param: 선택적 필터링/정렬/옵션

RESTful한 API를 설계하려면 이 기준을 일관되게 지키는 게 중요하다.
Swagger UI에서도 명확하게 표현되고, 클라이언트 개발자 입장에서도 예측 가능성이 높아진다.