FastAPI 경로 파라미터와 쿼리 파라미터 활용 가이드
AI Store에서 AI코딩으로 만들어진 앱을 만나보세요!
지금 바로 방문하기

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") 형식 사용
  • FastAPIEnum으로 경로 값 제한, Optional로 쿼리 파라미터의 선택성 처리 가능

섹션별 세부 요약

1. Path Parameters의 기초 및 예제

  • 경로 파라미터는 URL 경로에 포함되어 동적 값을 전달하며, 123 같은 ID 식별에 사용
  • 예시: @app.get("/items/{item_id}")item_idint로 자동 검증
  • FastAPI는 Enum을 사용해 허용된 값 제한 가능: Category.books, Category.electronics
  • 복수 파라미터 처리 예: /school/{school_id}/student/{student_id} → 두 개의 int 값 검증

2. Query Parameters의 기능 및 예제

  • 쿼리 파라미터는 필터링, 페이징, 정렬에 사용되며, ? 뒤에 추가됨
  • 예시: @app.get("/search")qlimitstrint로 전달 가능
  • 선택적 파라미터는 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의 자동 검증 기능을 활용해 타입 오류를 사전에 방지하세요.