Path, Query, Body 파라미터로 API의 유연함을 만들다

FastAPI의 진정한 강점 중 하나는 다양한 방식으로 클라이언트의 입력을 받아들여, 동적이고 유연한 웹 API를 쉽게 설계할 수 있다는 점입니다. 이 장에서는 반드시 알아야 할 세 가지 입력 방식, 즉 Path, Query, Body 파라미터를 실제 예제와 함께 살펴봅니다.

경로(Path) 파라미터: URL에 의미를 담다

웹 API에서 자주 쓰이는 패턴은 정보의 식별자를 URL 경로에 직접 담는 것입니다. FastAPI에서는 간결한 방식으로 이런 Path 파라미터를 정의할 수 있습니다. 예를 들어 /items/{item_id}라는 경로가 있다면, 함수의 인자에 동일한 변수명을 지정하면 자동으로 값을 전달받습니다.

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

타입까지 명확히 지정해주면, 숫자가 아닌 값이 들어올 경우 FastAPI가 알아서 에러를 처리합니다. 덕분에 데이터 검증 부담이 줄고, 오류 가능성이 낮아집니다.

쿼리(Query) 파라미터: 옵션과 검색에 활용하다

Path 파라미터가 경로에 직접 식별자를 담는다면, Query 파라미터는 좀 더 다양한 선택지나 조건, 검색 등에 적합합니다. URL에서 ? 뒤에 붙어 key=value 형태로 여러 개를 붙일 수 있으며, FastAPI에서는 함수의 기본 매개변수 혹은 명시적 Query 선언을 통해 이를 받아들입니다. 예를 들어:

@app.get("/search")
def search_items(keyword: str, page: int = 1):
    return {"keyword": keyword, "page": page}

여기서 page 파라미터처럼 기본값을 지정하면 선택사항이 되고, 명시하지 않으면 에러 없이 자동으로 기본값이 적용됩니다. Query 객체를 활용하면 더욱 세밀한 제한도 줄 수 있습니다.

바디(Body) 파라미터: 구조화된 데이터의 처리

복잡한 정보를 전달할 때는 주로 HTTP 요청의 본문에 JSON 형식으로 데이터를 담습니다. FastAPI에서는 Pydantic 모델을 이용해 Body 파라미터를 선언하고, 마치 함수 인자처럼 사용할 수 있습니다.

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float

@app.post("/items/")
def create_item(item: Item):
    return item

이 방식은 단일 값이 아닌 구조체 데이터의 입력이 필요할 때 용이합니다. 또한 자동으로 데이터의 타입과 형식 체크가 이루어져 개발자는 비즈니스 로직에만 집중하면 됩니다.

세 가지 방식의 조화로운 사용

FastAPI는 Path, Query, Body 파라미터를 혼합하여 쓰는 것을 자연스럽게 지원합니다. 각기 다른 입력이 어디에서 오는지 명확히 구분되어, 복잡한 API도 쉽게 구축할 수 있습니다. 예를 들면:

@app.put("/users/{user_id}")
def update_user(user_id: int, age: int | None = None, info: Item | None = None):
    return {"user_id": user_id, "age": age, "info": info}

Path로 식별자를 받고, Query로 옵션을 추가하며, Body로 구조화된 데이터를 접수하는 모습입니다.

실전에서 주의할 점과 팁

• Path, Query, Body 파라미터 명은 함수 인자의 이름과 반드시 일치해야 합니다.

• 타입 힌트를 활용하여 잘못된 데이터가 들어오는 것을 미리 방지할 수 있습니다.

• Body 파라미터는 GET 요청에서는 잘 사용하지 않으니 주의해야 합니다.

• pydantic의 강력한 검증 기능을 적극 활용하면, 입력 데이터의 신뢰성을 크게 높일 수 있습니다.

FastAPI의 입력 파라미터 시스템은 복잡해 보일 수 있으나, 올바르게 활용하면 효율적이고 견고한 API 설계가 가능합니다. 다음 장에서는 이 파라미터들을 실제 애플리케이션 아키텍처에서 어떻게 활용하는지, 그리고 다양한 확장 팁을 알아보겠습니다.