FastAPI Query vs Body 예제 및 특징 비교

fastapi에서 유저에게 요청 파라미터를 받는 방식으로 Query와 Body를 많이 사용하는데요.

이번 글에서는 이 두 가지 방식의 구현 방법과 차이에 대해서 간략하게 정리해보도록 하겠습니다.

 

 

Query parameters 사용 예제

fastapi에서 Query를 이용하여 파라미터 요청을 받는 예시 코드는 다음과 같습니다.

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
async def read_items(item_id: int = Query(...), q: str = Query(None)):
    return {"item_id": item_id, "q": q}

 

해당 예시에서는 item_id는 필수 파라미터, q는 선택 파라미터가 됩니다.

 

위의 코드로 구현한 경우, 요청을 보내는 curl의 예시 구문은 다음과 같습니다.

(모든 요청 사항이 url 내에 전부 포함된 형태입니다.)

curl -X GET http://api_url/items?item_id=1&q=search_term

 

참고로, Query 방식은 get 메소드를 구현하는 형태로 많이 사용되는 편입니다.

 

 

Request Body 사용 예제

이번에는 Request Body를 이용하여 요청 파라미터를 받는 예시 코드를 살펴보겠습니다.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

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

 

Body의 형태를 정의하기 위한 pydantic의 BaseModel을 상속한 class 선언이 필요하며,

위처럼 각 필드의 자료형(str, float 등)과 필수 여부(name과 price가 필수)를

명료하게 지정할 수 있다는 특징이 있습니다.

 

위 코드를 실행하는 curl 예문은 다음과 같이 요청 헤더(-H) 및

요청 본문 데이터 지정(-d)을 통하여 이루어지게 됩니다.

curl -X POST "http://api_url/items/" -H "Content-Type: application/json" -d '{"name":"Foo", "description":"A great item", "price":42.0, "tax":3.2}'

 

Request Body 방식은 post, patch, put, delete 등의 메소드에서 주로 사용되는 편입니다.

 

 

Query vs Body 방식 특징 비교

이 두 방식의 주요 특징들을 비교하면 다음과 같은 표로 정리해볼 수 있습니다.

특징	Query Parameters	Request Body
사용 HTTP 메서드	주로 GET	POST, PATCH, PUT, DELETE 등
데이터 위치	URL의 쿼리 스트링	HTTP 요청 본문
데이터 용량	제한적	제한 없음
보안성	낮음(URL에 노출)	높음(HTTPS 사용 시 암호화됨)
사용 용도	필터링, 검색, 간단한 데이터 전송	구조화된 데이터 전송, 생성, 업데이트