FastAPI는 Python으로 API를 개발할 때 매우 간단하고 효율적으로 쿼리 매개변수를 처리할 수 있는 기능을 제공한다.
쿼리 매개변수란?
쿼리 매개변수는 URL 경로의 일부가 아닌, ?key=value 형식으로 전달되는 데이터를 의미한다. 예를 들어, https://example.com/items?name=apple&limit=10이라는 URL에서 name과 limit은 쿼리 매개변수이다. 쿼리 매개변수를 사용하면 클라이언트가 다양한 필터링, 정렬, 페이징 등의 조건을 API에 전달할 수 있다.
FastAPI는 이러한 쿼리 매개변수를 매우 간단하게 처리할 수 있도록 도와준다.
쿼리 매개변수 사용법
기본 사용법
FastAPI에서 쿼리 매개변수를 정의하려면, 함수의 인자로 이름과 타입을 지정하면 된다. 예를 들어, 특정 이름의 아이템을 검색하는 API를 만들어 보자.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
def read_item(name: str):
return {"name": name}위 코드에서는 name이라는 쿼리 매개변수를 정의하고, 이를 함수의 인자로 전달받고 있다. 클라이언트가 ?name=apple과 같이 요청을 보내면, name 매개변수는 "apple" 값을 가지게 된다.
기본값과 선택적 쿼리 매개변수
쿼리 매개변수는 기본값을 가질 수 있으며, 기본값이 있는 경우 클라이언트가 해당 매개변수를 생략할 수 있다. 예를 들어, 아이템 목록을 조회할 때 limit과 offset 값을 선택적으로 받아서 페이징 처리를 할 수 있다.
@app.get("/items/")
def read_items(limit: int = 10, offset: int = 0):
return {"limit": limit, "offset": offset}이 경우, 클라이언트가 ?limit=5와 같이 요청을 보내면 limit은 5로 설정되며, offset은 기본값인 0이 사용된다. 쿼리 매개변수를 생략하면, 두 매개변수 모두 기본값이 사용된다.
선택적 매개변수 및 None 값 처리
쿼리 매개변수가 선택적이고, 값을 제공하지 않을 경우 None으로 처리하고 싶다면 다음과 같이 작성할 수 있다.
@app.get("/items/")
def read_items(name: str = None):
if name:
return {"name": name}
else:
return {"message": "No name provided"}이 경우, 클라이언트가 name 쿼리 매개변수를 제공하지 않으면 name은 None이 되고, 적절한 메시지를 반환할 수 있다.
복수의 쿼리 매개변수 사용
FastAPI는 여러 개의 쿼리 매개변수를 쉽게 처리할 수 있습니다. 다음 예제는 name과 category 두 개의 쿼리 매개변수를 사용하는 API입니다.
@app.get("/items/")
def read_items(name: str = None, category: str = None):
return {"name": name, "category": category}클라이언트가 ?name=apple&category=fruit와 같이 요청을 보내면, name은 "apple", category는 "fruit" 값으로 설정된다.
필수 매개변수와 선택적 매개변수
일부 쿼리 매개변수는 필수로 설정하고, 일부는 선택적으로 처리할 수 있다. 필수 매개변수를 정의하려면 기본값을 지정하지 않으면 된다.
@app.get("/items/")
def read_items(name: str, category: str = "general"):
return {"name": name, "category": category}이 예제에서 name은 필수 매개변수이고, category는 선택적 매개변수이다. 클라이언트가 name 매개변수를 제공하지 않으면 FastAPI는 422 Unprocessable Entity 에러를 반환한다.
쿼리 매개변수와 경로 매개변수의 조합
쿼리 매개변수는 경로 매개변수와 함께 사용할 수 있다. 예를 들어, 특정 카테고리의 아이템을 조회하면서 이름으로 필터링하는 API를 만들어 보자.
@app.get("/categories/{category}/items/")
def read_category_items(category: str, name: str = None):
return {"category": category, "name": name}이 경우, 클라이언트는 categories/fruit/items/?name=apple과 같이 요청을 보낼 수 있으며, category는 "fruit", name은 "apple"로 설정된다.
쿼리 매개변수의 고급 기능
FastAPI는 단순히 쿼리 매개변수를 처리하는 것뿐만 아니라, 고급 기능도 제공한다. 예를 들어, Pydantic 모델을 사용하여 쿼리 매개변수를 더욱 구조적으로 관리할 수 있다.
from pydantic import BaseModel
class ItemQuery(BaseModel):
name: str
category: str = "general"
@app.get("/items/")
def read_items(query: ItemQuery):
return query.dict()이 예제에서는 ItemQuery라는 Pydantic 모델을 정의하고, 이를 통해 쿼리 매개변수를 관리하고 있다. 이렇게 하면 복잡한 쿼리 매개변수 처리를 보다 체계적으로 할 수 있다.
GET http://localhost:8000/items
content-Type: application/json
{
"name": "rudaks",
"category": "study"
}실행결과
{
"name": "rudaks",
"category": "study"
}
