FastAPI 서버개발, 경로 매개변수와 쿼리 매개변수

FastAPI는 Python으로 만든 웹 프레임워크로, 빠른 성능과 쉬운 사용성을 자랑합니다. 특히 RESTful API를 구축하는 데 강력한 도구를 제공합니다. 본 글에서는 FastAPI의 경로 매개변수와 쿼리 매개변수의 개념과 이들의 활용 방식에 대해 자세히 살펴보겠습니다.

1. FastAPI 개요

FastAPI는 스타트업부터 대규모 애플리케이션까지 다양한 환경에서 사용되는 현대적인 웹 프레임워크입니다. 이 프레임워크는 비동기 프로그래밍을 기본으로 하며, 자동 문서화 및 타입 검사를 지원합니다. 이러한 특징 덕분에 개발자는 효율적으로 API를 설계하고 구축할 수 있습니다.

1.1 FastAPI 설치하기

FastAPI를 사용하기 위해 먼저 FastAPI와 ASGI 서버(Uvicorn)를 설치해야 합니다. 아래의 명령어를 사용하여 설치할 수 있습니다.

pip install fastapi uvicorn

2. 경로 매개변수

경로 매개변수는 URL 경로의 일부로, 사용자가 요청하는 리소스를 동적으로 지정할 수 있게 해줍니다. URL 경로에서 변하는 부분을 변수처럼 설정하고, 이를 FastAPI 함수의 매개변수로 받아 처리할 수 있습니다.

2.1 경로 매개변수 사용 예제

다음은 경로 매개변수를 사용하는 간단한 FastAPI 애플리케이션의 예제입니다.

from fastapi import FastAPI

app = FastAPI()

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

위의 예에서 @app.get("/items/{item_id}")는 URL 경로의 item_id 부분을 매개변수로 받아, 이를 read_item 함수에서 사용할 수 있도록 합니다. 클라이언트가 /items/42와 같은 요청을 보내면, item_id는 42로 설정되고, JSON 형식으로 응답됩니다.

2.2 여러 경로 매개변수 사용하기

FastAPI에서는 여러 개의 경로 매개변수를 동시에 사용할 수 있습니다. 예를 들어, 다음과 같은 코드를 작성할 수 있습니다.

@app.get("/users/{user_id}/items/{item_id}")
async def read_user_item(user_id: int, item_id: int):
    return {"user_id": user_id, "item_id": item_id}

위의 예제는 사용자의 ID와 항목의 ID를 동시에 받아서 응답합니다. 클라이언트가 /users/1/items/10와 같은 요청을 보낼 경우, user_id와 item_id는 각각 1과 10으로 설정됩니다.

3. 쿼리 매개변수

쿼리 매개변수는 URL 경로 뒤에 추가되는 파라미터로, 클라이언트가 특정 데이터를 필터링하거나 페이지네이션할 때 종종 사용됩니다. URL의 물음표(?) 뒤에 설정되며, 여러 개의 매개변수를 “&”로 구분할 수 있습니다.

3.1 쿼리 매개변수 사용 예제

다음은 쿼리 매개변수를 사용하는 예제입니다.

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

위 코드는 기본적으로 skip과 limit 값을 받는 요청을 처리하며, 기본값은 각각 0과 10입니다. 클라이언트에서 /items/?skip=10&limit=5와 같은 요청을 보내면, skip은 10, limit은 5로 설정됩니다.

3.2 쿼리 매개변수와 경로 매개변수 혼용하기

FastAPI에서는 경로 매개변수와 쿼리 매개변수를 동시에 사용할 수 있습니다. 아래는 그 예제입니다.

@app.get("/users/{user_id}/items/")
async def read_user_items(user_id: int, skip: int = 0, limit: int = 10):
    return {"user_id": user_id, "skip": skip, "limit": limit}

이 예제에서는 사용자의 ID를 경로 매개변수로 받고, skip와 limit를 쿼리 매개변수로 사용합니다. 클라이언트가 /users/1/items/?skip=5&limit=10와 같은 요청을 보내면, 서버는 해당 사용자 ID와 쿼리 매개변수 값을 기반으로 응답을 처리합니다.

4. 경로 및 쿼리 매개변수의 유효성 검사

FastAPI는 Pydantic을 기반으로 하여 경로 및 쿼리 매개변수에 대한 유효성 검사를 자동으로 수행합니다. 타입 힌트를 사용하여 데이터 타입을 지정하면, 잘못된 형식의 데이터가 들어오는 경우 자동으로 422 Unprocessable Entity 응답이 발생합니다.

4.1 유효성 검사 예제

다음은 유효성 검사를 포함한 간단한 예제입니다.

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id <= 0:
        return {"error": "item_id는 1 이상의 정수여야 합니다."}
    return {"item_id": item_id}

위의 예제에서 item_id가 1보다 작거나 같을 경우 오류 메시지를 반환하며, 클라이언트에서는 항상 올바른 입력값을 제공해야 합니다.

5. 결론

FastAPI는 경로 매개변수와 쿼리 매개변수를 통해 RESTful API를 더욱 유연하고 편리하게 설계할 수 있는 강력한 기능을 제공합니다. 본 글에서 설명한 내용을 토대로 FastAPI를 활용하여 다양한 API 엔드포인트를 구축하고, 데이터 필터링 및 요청 처리를 보다 효율적으로 처리할 수 있습니다.

이제 여러분은 FastAPI에서 경로 매개변수와 쿼리 매개변수의 사용법을 익혔습니다. 이 기능을 바탕으로 더 복잡한 애플리케이션을 개발해 보시기 바랍니다. FastAPI의 높은 성능과 사용성을 경험하면서, 여러분의 프로젝트에 맞는 최적의 RESTful API를 구현해 보세요.