FastAPI 시리즈 6화 - Path, Query, Header, Cookie 파라미터 제대로 다루기

FastAPI의 Path, Query, Header, Cookie 파라미터 처리 방식을 실제 예제 중심으로 정리합니다. 타입 기반 자동 검증과 문서화까지 함께 알아봅니다.

 

---

 

API 파라미터를 다루는 방법은 4가지

 

FastAPI는 다양한 요청 요소를 자동으로 파싱하고 타입 검증까지 수행합니다.

HTTP 요청에는 다음과 같은 방식으로 파라미터가 포함됩니다:

구분설명FastAPI 처리 방식

Path 파라미터	/users/{id}	Path()
Query 파라미터	?q=search	Query()
Header	Authorization: ...	Header()
Cookie	클라이언트 저장 정보	Cookie()

 

 

---

 

1. Path 파라미터 – 경로에 포함된 변수

from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/users/{user_id}")
def read_user(user_id: int = Path(..., gt=0)):
    return {"user_id": user_id}

 

• Path(...): 필수 값 선언
• gt=0: 0보다 큰 정수만 허용
• 자동으로 문서화 UI에 조건 설명 추가됨

 

 

🔎 Swagger UI 반영

 

• 입력 필드: user_id
• 설명: Must be greater than 0

 

---

 

2. Query 파라미터 – 

?key=value

 형태

from fastapi import Query

@app.get("/search")
def search_items(q: str = Query(..., min_length=3, max_length=50)):
    return {"query": q}

 

• Query(...): 필수 쿼리 파라미터
• min_length, max_length: 문자열 길이 조건 추가

 

 

▶ URL 예시

 

GET /search?q=apple

 

 

▶ 옵션 요약

옵션설명

default	기본값 or 필수 여부 결정 (... = 필수)
min_length / max_length	문자열 조건
regex	정규표현식 매칭 조건

 

 

---

 

3. Header 파라미터 – 인증이나 토큰에서 사용

from fastapi import Header

@app.get("/header-check")
def check_token(token: str = Header(...)):
    return {"token_received": token}

 

▶ 요청 헤더 예시

GET /header-check HTTP/1.1
Host: localhost:8000
token: secret-token-123

 

🔍 주의

 

• FastAPI는 Header()를 통해 헤더 키를 자동 소문자로 변환 처리
• Authorization, X-User-ID 같은 헤더도 처리 가능 (단, 대시(-)는 언더스코어로)

def custom_header(x_user_id: str = Header(...)):
    ...

 

 

---

 

4. Cookie 파라미터 – 세션, 인증, 추적용 정보

from fastapi import Cookie

@app.get("/read-cookie")
def read_cookie(session_id: str = Cookie(None)):
    return {"session_id": session_id}

 

▶ 쿠키 예시

Cookie: session_id=abcd1234

 

• 기본값을 None으로 설정하면 쿠키가 없어도 에러 발생 안 함
• 유저 세션이나 로그인 유지 상태 추적에 활용

 

---

 

5. 조합 활용 예제

@app.get("/items/{item_id}")
def get_item(
    item_id: int = Path(..., gt=0),
    q: str = Query(None),
    token: str = Header(...),
    session_id: str = Cookie(None)
):
    return {
        "item_id": item_id,
        "query": q,
        "token": token,
        "session_id": session_id
    }

 

• 실전에서는 여러 파라미터를 조합해 처리하는 경우가 일반적
• FastAPI는 위치만 잘 지정하면 자동으로 파라미터를 파싱하고 문서화까지 수행

 

---

 

문서화 반영 구조

 

FastAPI는 각 파라미터마다:

 

• 유형(Path/Query/Header/Cookie) 구분
• 타입(str, int, float 등)에 따라 검증 자동 처리
• 제약 조건(min_length, gt 등) 기반으로 Swagger에 자동 설명 생성

 

덕분에 기획자/프론트엔드/QA와의 협업이 매우 효율적입니다.

 

---

 

정리 – 요청 파라미터는 FastAPI의 장점이 집약된 기능

파라미터함수 데코레이터설명

Path	Path()	URL 경로 변수
Query	Query()	쿼리 스트링
Header	Header()	HTTP 헤더
Cookie	Cookie()	쿠키 값

모든 파라미터는:

 

• 타입 기반 자동 파싱
• 제약 조건 설정 가능
• 문서 자동 반영
• 검증 실패 시 422 오류 반환

 

---

 

다음 글 예고

 

FastAPI 시리즈 7화 - Response 모델과 응답 커스터마이징

에서는 응답 데이터의 포맷을 조절하고,

상태 코드, 헤더, 콘텐츠 타입까지 실전 API 응답 설계 방식을 소개합니다.