API 버전 관리는 소프트웨어 개발에서 중요한 측면 중 하나입니다. 새로운 기능을 추가하거나 기존 기능을 수정할 때, 기존 API와 호환성 유지를 위해 새로운 버전을 도입하는 것이 일반적입니다.

이번 블로그에서는 Python의 FastAPI 프레임워크를 사용하여 API 버전 관리의 주요 측면을 살펴보고, 간단한 예제를 통해 FastAPI를 사용하여 버전 관리하는 방법을 소개합니다.

FastAPI 소개

FastAPI는 높은 성능과 사용하기 쉬운 API를 빠르게 구축할 수 있도록 지원하는 Python 웹 프레임워크입니다. FastAPI는 자동 문서 생성, 데이터 유효성 검사, 타입 힌팅 등 많은 기능을 제공하므로 API를 쉽게 관리할 수 있습니다.

API 버전 관리의 중요성

API 버전 관리는 클라이언트와의 호환성을 유지하고 새로운 기능을 안정적으로 추가하기 위해 필요합니다. 새로운 엔드포인트 또는 쿼리 매개변수를 도입할 때, 기존 버전과의 충돌을 방지하고, 사용자들이 쉽게 새로운 기능을 채용할 수 있도록 버전 관리가 중요합니다.

FastAPI를 사용한 API 버전 관리 방법

경로 매개변수를 사용한 버전 관리

FastAPI를 사용하여 API 버전을 관리하는 한 가지 방법은 경로 매개변수를 사용하는 것입니다. 이를 통해 각 버전의 엔드포인트를 분리하고 관리할 수 있습니다.

다음은 FastAPI를 사용하여 버전 관리하는 간단한 예제입니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/v1/items/")
async def read_items_v1():
    return {"version": "v1", "items": [{"item_id": "foo"}, {"item_id": "bar"}]}

@app.get("/v2/items/")
async def read_items_v2():
    return {"version": "v2", "items": [{"item_id": "foo"}, {"item_id": "bar"}, {"item_id": "baz"}]}

위의 예제에서 /v1/items/와 /v2/items/는 각각 v1 및 v2 버전의 엔드포인트를 나타냅니다.

헤더를 사용한 버전 관리

또 다른 방법은 HTTP 헤더를 사용하여 API 버전을 관리하는 것입니다. 클라이언트 요청의 헤더에서 버전 정보를 읽고, 해당 버전에 맞는 로직을 처리하는 방식입니다.

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

@app.get("/items/")
async def read_items(version: int = Header(...)):
    if version == 1:
        return {"version": "v1", "items": [{"item_id": "foo"}, {"item_id": "bar"}]}
    elif version == 2:
        return {"version": "v2", "items": [{"item_id": "foo"}, {"item_id": "bar"}, {"item_id": "baz"}]}
    else:
        raise HTTPException(status_code=400, detail="Invalid version")

위의 예제에서 version 헤더를 통해 버전을 전달받고, 해당 버전에 맞는 응답을 전송합니다.

마무리

FastAPI를 사용하여 API 버전을 관리하는 방법을 살펴보았습니다. 경로 매개변수 및 헤더를 사용하여 버전을 구분하는 방법을 살펴보았으며, 각각의 장단점을 고려하여 적합한 방법을 선택할 수 있습니다. API 버전 관리는 신중한 계획과 유연한 전략이 필요하며, FastAPI를 활용하여 이를 쉽게 구현할 수 있습니다.