FastAPI에서 경로 파라미터(Path Parameters)와 쿼리 파라미터(Query Parameters) 활용 가이드
카테고리
프로그래밍/소프트웨어 개발
서브카테고리
웹 개발
대상자
- FastAPI를 사용하는 백엔드 개발자
- RESTful API 설계를 공부하는 초보 개발자
- 중간 수준의 Python 및 FastAPI 경험자
핵심 요약
- Path Parameters는 특정 리소스를 식별하기 위해 URL 경로에 포함되는 필수 값으로,
@app.get("/items/{item_id}")
와 같은 형식으로 정의 - Query Parameters는 필터링, 정렬, 페이징 등의 기능을 위해 URL의
?
뒤에 추가되는 선택적 값으로,@app.get("/search?q=shoes&limit=10")
형식 사용 - FastAPI는
Enum
으로 경로 값 제한,Optional
로 쿼리 파라미터의 선택성 처리 가능
섹션별 세부 요약
1. Path Parameters의 기초 및 예제
- 경로 파라미터는 URL 경로에 포함되어 동적 값을 전달하며,
123
같은 ID 식별에 사용 - 예시:
@app.get("/items/{item_id}")
→item_id
를int
로 자동 검증 - FastAPI는
Enum
을 사용해 허용된 값 제한 가능:Category.books
,Category.electronics
- 복수 파라미터 처리 예:
/school/{school_id}/student/{student_id}
→ 두 개의int
값 검증
2. Query Parameters의 기능 및 예제
- 쿼리 파라미터는 필터링, 페이징, 정렬에 사용되며,
?
뒤에 추가됨 - 예시:
@app.get("/search")
→q
와limit
을str
및int
로 전달 가능 - 선택적 파라미터는
Optional
사용:brand: Optional[str] = None
- 예시:
/products?brand=Nike&limit=5
→ 브랜드와 결과 수 제한
3. Path와 Query Parameters의 비교 및 사용 사례
- Path Parameter 사용 사례:
- 특정 리소스 식별: /users/101
→ 사용자 ID 101 조회
- 필수 값으로 URL 구조에 포함
- Query Parameter 사용 사례:
- 필터링: /products?category=electronics
- 페이징: /users?page=2&limit=25
- 선택적 입력으로 유연한 API 설계 가능
결론
- 필수 리소스 식별에는 Path Parameters
를, 필터링/조정에는 Query Parameters
를 사용하세요.
- Enum
으로 경로 값 제한, Optional
로 쿼리 파라미터 선택성 설정하는 것이 실무에서 효과적입니다.
- FastAPI의 자동 검증 기능을 활용해 타입 오류를 사전에 방지하세요.