FastAPI는 Python으로 API를 개발할 때 요청 본문을 간단하고 효율적으로 처리할 수 있는 강력한 기능을 제공한다.
요청 본문(Request Body)란?
요청 본문은 클라이언트가 서버로 데이터를 전송할 때 사용하는 HTTP 요청의 일부이다. 일반적으로 POST, PUT, PATCH와 같은 메서드에서 사용되며, JSON, XML, Form 데이터 등 다양한 형식으로 데이터를 전송할 수 있다.
FastAPI는 요청 본문을 처리하는 데 있어서 Pydantic 모델을 사용하여 데이터 검증과 변환을 간편하게 해준다. 이를 통해 API 개발자는 구조화된 데이터를 손쉽게 다룰 수 있다.
요청 본문 처리의 기본 개념
FastAPI에서 요청 본문을 처리하려면, Pydantic 모델을 정의하고 이를 경로 함수의 매개변수로 지정하면 된다. Pydantic은 FastAPI와 함께 사용되는 데이터 검증 라이브러리로, 입력 데이터를 자동으로 검증하고 변환해 준다.
Pydantic 모델 정의하기
먼저, 요청 본문에서 사용할 데이터를 표현할 Pydantic 모델을 정의해 보자. 예를 들어, 아이템의 이름과 가격을 포함한 요청 본문을 처리하려면 다음과 같이 모델을 정의할 수 있다.
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float여기서 Item 모델은 name과 price 필드를 가지고 있으며, 각각 str과 float 타입으로 정의되었다.
요청 본문 받기
이제 정의한 Pydantic 모델을 사용하여 요청 본문을 처리하는 API 엔드포인트를 만들어 보자. 아래 예제에서는 클라이언트가 JSON 형식으로 전송한 아이템 데이터를 받아 처리한다.
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
price: float
@app.post("/items/")
def create_item(item: Item):
return {"name": item.name, "price": item.price}이 API는 POST 요청을 받으며, 클라이언트가 전송한 JSON 데이터를 Item 모델로 변환한 후, 해당 데이터를 응답으로 반환한다.
클라이언트가 다음과 같이 요청을 보낸다고 가정해 보자.
{
"name": "Laptop",
"price": 999.99
}그러면 FastAPI는 이 데이터를 자동으로 Item 모델로 변환하고, 응답으로 JSON 형태의 데이터를 반환한다.
요청 본문 데이터 검증
Pydantic 모델을 사용하면 요청 본문의 데이터가 자동으로 검증됩니다. 예를 들어, price 필드에 숫자가 아닌 문자열을 전달하면 FastAPI는 자동으로 422 Unprocessable Entity 에러를 반환한다.
@app.post("/items/")
def create_item(item: Item):
return item잘못된 데이터를 전송하는 경우의 응답 예시는 다음과 같다.
{
"detail": [
{
"loc": ["body", "price"],
"msg": "value is not a valid float",
"type": "type_error.float"
}
]
}이렇게 자동화된 데이터 검증 덕분에 API의 신뢰성과 안정성이 크게 향상된다.
선택적 필드와 기본값 처리
Pydantic 모델에서 필드는 선택적으로 정의할 수 있으며, 기본값을 지정할 수도 있습니다. 예를 들어, description 필드를 선택적으로 추가하고, 기본값을 설정하는 방법은 다음과 같습니다.
class Item(BaseModel):
name: str
price: float
description: str = "No description provided"
@app.post("/items/")
def create_item(item: Item):
return item이 경우 클라이언트가 description 필드를 제공하지 않으면, 기본값인 "No description provided"가 사용된다.
요청 본문에서 복잡한 데이터 구조 처리
요청 본문에서 중첩된 데이터 구조를 처리하는 것도 가능하다. 예를 들어, 아이템의 판매자 정보를 포함한 데이터를 처리하려면 다음과 같이 중첩된 Pydantic 모델을 정의할 수 있다.
class Seller(BaseModel):
name: str
rating: float
class Item(BaseModel):
name: str
price: float
seller: Seller
@app.post("/items/")
def create_item(item: Item):
return item이제 클라이언트는 다음과 같은 JSON 데이터를 전송할 수 있다.
{
"name": "Laptop",
"price": 999.99,
"seller": {
"name": "TechStore",
"rating": 4.8
}
}FastAPI는 이 복잡한 데이터 구조를 자동으로 처리하고, 적절한 Pydantic 모델로 변환하여 사용할 수 있다.
요청 본문과 경로 매개변수, 쿼리 매개변수의 조합
FastAPI는 요청 본문, 경로 매개변수, 쿼리 매개변수를 조합하여 사용할 수 있다. 예를 들어, 특정 카테고리에 속하는 아이템을 생성하는 API를 만들어 보자.
@app.post("/categories/{category}/items/")
def create_item(category: str, item: Item, discount: float = 0.0):
return {
"category": category,
"item": item,
"discount": discount
}이 API에서는 category라는 경로 매개변수와 item이라는 요청 본문, 그리고 discount라는 쿼리 매개변수를 조합하여 사용한다.
클라이언트는 다음과 같은 방식으로 요청을 보낼 수 있다.
POST /categories/electronics/items/?discount=10.0
{
"name": "Laptop",
"price": 999.99
}이 경우 응답은 다음과 같이 반환된다.
{
"category": "electronics",
"item": {
"name": "Laptop",
"price": 999.99
},
"discount": 10.0
}
