FastAPI로 REST API 만들기 – 초보자도 쉽게 따라하는 완벽 가이드

1. 도입 – 학습 목표 및 필요성

FastAPI로 REST API 만들기는 현대 웹 개발에서 필수적인 기술입니다. FastAPI는 Python 기반의 고성능 웹 프레임워크로, 빠른 개발 속도와 자동 문서화 기능을 제공합니다. 이 튜토리얼에서는 FastAPI의 기초부터 실전 활용까지 단계별로 학습하게 됩니다. 초보자도 쉽게 따라할 수 있도록 구성되어 있으며, 실제 프로젝트에 바로 적용할 수 있는 실용적인 예제를 포함합니다. API 개발의 핵심 개념을 이해하고, 데이터베이스 연동, 인증, 검증 등 실무에서 필요한 기능들을 모두 다룹니다. 이 가이드를 통해 여러분은 프로덕션 레벨의 REST API를 구축할 수 있는 능력을 갖추게 될 것입니다.

2. 기본 개념 설명

FastAPI란?
FastAPI는 Starlette와 Pydantic을 기반으로 한 최신 Python 웹 프레임워크입니다. 타입 힌트를 활용하여 자동으로 데이터 검증과 API 문서를 생성하며, NodeJS나 Go에 필적하는 높은 성능을 자랑합니다.

REST API 핵심 개념
REST(Representational State Transfer)는 HTTP 프로토콜을 활용한 아키텍처 스타일입니다. GET, POST, PUT, DELETE 등의 HTTP 메서드를 사용하여 리소스를 처리하며, 상태를 유지하지 않는(stateless) 특징을 가집니다. JSON 형식으로 데이터를 주고받으며, URL을 통해 리소스를 식별합니다.

FastAPI의 장점
1. 빠른 성능: 비동기 처리 지원으로 높은 처리량 제공
2. 자동 문서화: Swagger UI와 ReDoc 자동 생성
3. 타입 안정성: Pydantic을 통한 자동 데이터 검증
4. 직관적인 문법: Python 타입 힌트를 활용한 명확한 코드
5. 현대적 표준: OpenAPI, JSON Schema 완벽 지원

3. 단계별 구현 가이드

3.1 환경 설정

먼저 Python 3.7 이상이 설치되어 있어야 합니다. 가상 환경을 생성하고 필요한 패키지를 설치합니다.

# 가상 환경 생성
python -m venv venv

# 가상 환경 활성화 (Windows)
venv\Scripts\activate

# 가상 환경 활성화 (Mac/Linux)
source venv/bin/activate

# FastAPI 및 ASGI 서버 설치
pip install fastapi uvicorn[standard]
pip install pydantic sqlalchemy

3.2 기본 애플리케이션 생성

프로젝트 폴더를 만들고 main.py 파일을 생성합니다. 가장 간단한 FastAPI 애플리케이션부터 시작해보겠습니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello World"}

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

애플리케이션을 실행하려면 터미널에서 다음 명령어를 입력합니다:

uvicorn main:app --reload

브라우저에서 http://localhost:8000으로 접속하면 결과를 확인할 수 있으며, http://localhost:8000/docs에서 자동 생성된 API 문서를 볼 수 있습니다.

3.3 데이터 모델 정의

Pydantic 모델을 사용하여 요청과 응답 데이터의 구조를 정의합니다. 이를 통해 자동 검증과 명확한 API 스펙을 제공할 수 있습니다.

from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = None
    price: float = Field(..., gt=0)
    tax: Optional[float] = None

class ItemResponse(BaseModel):
    id: int
    name: str
    price: float
    total_price: float

3.4 CRUD 엔드포인트 구현

Create, Read, Update, Delete 기능을 구현하여 완전한 REST API를 만듭니다. 실제 데이터베이스 대신 메모리 저장소를 사용하여 학습용으로 구성합니다.

from typing import List
from fastapi import HTTPException

# 메모리 데이터베이스
items_db = {}
item_id_counter = 1

@app.post("/items/", response_model=ItemResponse)
def create_item(item: Item):
    global item_id_counter
    item_id = item_id_counter
    item_id_counter += 1
    
    total_price = item.price + (item.tax or 0)
    items_db[item_id] = {**item.dict(), "id": item_id}
    
    return ItemResponse(
        id=item_id,
        name=item.name,
        price=item.price,
        total_price=total_price
    )

@app.get("/items/{item_id}", response_model=ItemResponse)
def get_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    
    item = items_db[item_id]
    total_price = item["price"] + (item.get("tax") or 0)
    
    return ItemResponse(
        id=item["id"],
        name=item["name"],
        price=item["price"],
        total_price=total_price
    )

@app.get("/items/", response_model=List[ItemResponse])
def list_items(skip: int = 0, limit: int = 10):
    items_list = list(items_db.values())[skip:skip+limit]
    return [
        ItemResponse(
            id=item["id"],
            name=item["name"],
            price=item["price"],
            total_price=item["price"] + (item.get("tax") or 0)
        )
        for item in items_list
    ]

@app.put("/items/{item_id}", response_model=ItemResponse)
def update_item(item_id: int, item: Item):
    if item_id not in items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    
    items_db[item_id].update(item.dict())
    updated_item = items_db[item_id]
    total_price = updated_item["price"] + (updated_item.get("tax") or 0)
    
    return ItemResponse(
        id=item_id,
        name=updated_item["name"],
        price=updated_item["price"],
        total_price=total_price
    )

@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    
    del items_db[item_id]
    return {"message": "Item deleted successfully"}

4. 실제 코드 예제와 설명

실무에서 자주 사용되는 패턴들을 살펴보겠습니다.

4.1 의존성 주입 (Dependency Injection)

FastAPI의 강력한 기능 중 하나는 의존성 주입 시스템입니다. 데이터베이스 세션, 인증 등을 깔끔하게 관리할 수 있습니다.

from fastapi import Depends, Header, HTTPException

async def verify_token(x_token: str = Header()):
    if x_token != "secret-token":
        raise HTTPException(status_code=400, detail="Invalid token")
    return x_token

@app.get("/protected/")
async def protected_route(token: str = Depends(verify_token)):
    return {"message": "Access granted", "token": token}

4.2 요청 검증 및 에러 처리

Pydantic의 Field를 활용하여 상세한 검증 규칙을 정의할 수 있습니다.

from pydantic import BaseModel, Field, validator
from datetime import datetime

class User(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: str = Field(..., regex=r'^[\w\.-]+@[\w\.-]+\.\w+$')
    age: int = Field(..., ge=0, le=150)
    created_at: datetime = Field(default_factory=datetime.now)
    
    @validator('username')
    def username_alphanumeric(cls, v):
        assert v.isalnum(), 'must be alphanumeric'
        return v

@app.post("/users/")
def create_user(user: User):
    return {"user": user, "message": "User created successfully"}

4.3 비동기 처리

FastAPI는 async/await를 지원하여 비동기 처리를 쉽게 구현할 수 있습니다.

import asyncio
from typing import List

@app.get("/async-items/")
async def get_async_items():
    # 비동기 데이터베이스 쿼리 시뮬레이션
    await asyncio.sleep(0.1)
    return {"items": ["item1", "item2", "item3"]}

@app.get("/concurrent-data/")
async def get_concurrent_data():
    # 여러 비동기 작업을 동시에 실행
    task1 = asyncio.create_task(fetch_data_from_api_1())
    task2 = asyncio.create_task(fetch_data_from_api_2())
    
    result1 = await task1
    result2 = await task2
    
    return {"data1": result1, "data2": result2}

async def fetch_data_from_api_1():
    await asyncio.sleep(0.5)
    return {"source": "API 1", "data": [1, 2, 3]}

async def fetch_data_from_api_2():
    await asyncio.sleep(0.5)
    return {"source": "API 2", "data": [4, 5, 6]}

5. 고급 활용 방법

5.1 데이터베이스 연동 (SQLAlchemy)

실제 프로젝트에서는 데이터베이스를 사용합니다. SQLAlchemy를 활용한 예제입니다.

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session

DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

class UserDB(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True, index=True)
    username = Column(String, unique=True, index=True)
    email = Column(String, unique=True)

Base.metadata.create_all(bind=engine)

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.post("/db-users/")
def create_db_user(user: User, db: Session = Depends(get_db)):
    db_user = UserDB(username=user.username, email=user.email)
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user

5.2 미들웨어와 CORS 설정

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

5.3 백그라운드 태스크

from fastapi import BackgroundTasks

def send_notification(email: str, message: str):
    # 이메일 발송 로직
    print(f"Sending email to {email}: {message}")

@app.post("/send-notification/{email}")
async def notify(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(send_notification, email, "Welcome!")
    return {"message": "Notification sent in background"}

6. 마무리 및 추가 학습 자료

이 FastAPI로 REST API 만들기 튜토리얼을 통해 기본부터 고급 기능까지 학습했습니다. FastAPI의 강력한 기능들을 활용하면 효율적이고 안정적인 API를 빠르게 개발할 수 있습니다. 계속해서 학습을 이어가기 위해서는 공식 문서(https://fastapi.tiangolo.com)를 참고하고, 실제 프로젝트에 적용해보는 것을 추천합니다. 인증(JWT), 테스팅(pytest), 배포(Docker, Kubernetes) 등 더 깊이 있는 주제들도 공부해보세요. FastAPI 커뮤니티는 매우 활발하므로 GitHub 이슈와 Stack Overflow에서 많은 도움을 받을 수 있습니다. 지속적인 연습과 실전 경험을 통해 전문성을 키워나가시기 바랍니다!