백엔드 기초집: Python FastAPILESSON 05

Path Parameter와 Query Parameter

난이도초급

예상 시간35분

선수지식이전 강의

5강. Path Parameter와 Query Parameter

1. 이번 강의에서 해결할 문제

하나의 기록을 고르거나 특정 게임의 기록만 조회하려면 URL에서 값을 받아야 합니다. 식별자와 선택 조건을 구분해 설계합니다.

2. 학습 목표

3. 핵심 개념

Path Parameter는 /records/12처럼 특정 리소스의 정체성을 나타내며 보통 필수입니다. Query Parameter는 /records?game_name=Rule+Break&limit=20처럼 필터, 정렬, 페이지 크기 같은 선택 조건에 적합합니다. FastAPI는 타입 힌트와 Pydantic 검증을 OpenAPI 문서에도 반영합니다.

4. 단계별 코드 예시

파일 경로: game-ranking-api/app/main.py

app/main.py
from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI(title="Game Ranking API")


@app.get("/records/{record_id}")
def get_record(
    record_id: Annotated[int, Path(ge=1)],
) -> dict[str, int]:
    return {"record_id": record_id}


@app.get("/records")
def list_records(
    game_name: Annotated[str | None, Query(min_length=1, max_length=80)] = None,
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
) -> dict[str, object]:
    return {"game_name": game_name, "limit": limit, "items": []}

실행 위치: game-ranking-api/

python -m uvicorn app.main:app --reload
Invoke-RestMethod 'http://127.0.0.1:8000/records/3'
Invoke-RestMethod 'http://127.0.0.1:8000/records?game_name=Rule%20Break&limit=10'
Invoke-WebRequest 'http://127.0.0.1:8000/records/0' -SkipHttpErrorCheck

5. 코드가 동작하는 이유

라우트의 {record_id}와 함수 인자 이름이 연결됩니다. ge=1은 1 이상을, le=100은 100 이하를 요구합니다. game_name은 기본값이 None이므로 선택 입력이며, FastAPI가 문자열과 정수 변환 및 오류 응답을 자동 처리합니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ