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

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

FastAPI로 REST API 만들기는 현대 웹 개발에서 필수적인 기술입니다. FastAPI는 Python 3.7+ 기반의 고성능 웹 프레임워크로, 빠른 개발 속도와 뛰어난 성능을 자랑합니다. 이 튜토리얼을 통해 여러분은 실제 프로젝트에 바로 적용할 수 있는 REST API를 구축하는 방법을 배우게 됩니다. FastAPI는 자동 문서화, 타입 힌팅, 비동기 처리 등 강력한 기능을 제공하여 생산성을 극대화할 수 있습니다. 백엔드 개발자를 꿈꾸거나 API 개발 실력을 향상시키고 싶다면, 이 가이드가 완벽한 출발점이 될 것입니다.

2. 기본 개념 설명

REST API란?
REST(Representational State Transfer)는 웹 서비스를 위한 아키텍처 스타일입니다. HTTP 메서드(GET, POST, PUT, DELETE)를 사용하여 자원을 관리하며, 클라이언트와 서버 간의 효율적인 통신을 가능하게 합니다.

FastAPI의 특징
– 빠른 성능: Starlette와 Pydantic 기반으로 NodeJS와 Go에 필적하는 속도
– 자동 문서화: Swagger UI와 ReDoc를 통한 대화형 API 문서 자동 생성
– 타입 안정성: Python 타입 힌트를 활용한 데이터 검증 및 자동 완성
– 비동기 지원: async/await를 통한 고성능 비동기 처리
– 표준 기반: OpenAPI 및 JSON Schema 표준 완벽 준수

FastAPI는 Flask의 간결함과 Django의 강력함을 결합한 현대적인 프레임워크로, 마이크로서비스와 API 중심 애플리케이션 개발에 최적화되어 있습니다.

3. 단계별 구현 가이드

Step 1: 환경 설정

먼저 Python 가상 환경을 생성하고 FastAPI를 설치합니다.

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

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

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

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

Step 2: 프로젝트 구조 설계

체계적인 프로젝트 구조를 만드는 것이 중요합니다.

my_api_project/
├── app/
│   ├── __init__.py
│   ├── main.py          # 메인 애플리케이션
│   ├── models.py        # 데이터 모델
│   ├── schemas.py       # Pydantic 스키마
│   └── routers/         # API 라우터
│       └── items.py
├── requirements.txt
└── .env

Step 3: 기본 애플리케이션 생성

FastAPI 인스턴스를 생성하고 첫 번째 엔드포인트를 만듭니다.

# app/main.py
from fastapi import FastAPI
from typing import Optional

app = FastAPI(
    title="My REST API",
    description="FastAPI로 만든 RESTful API",
    version="1.0.0"
)

@app.get("/")
async def root():
    return {"message": "Welcome to FastAPI!"}

@app.get("/health")
async def health_check():
    return {"status": "healthy"}

Step 4: 데이터 모델 정의

Pydantic을 사용하여 데이터 검증 모델을 만듭니다.

# app/schemas.py
from pydantic import BaseModel, Field
from typing import Optional
from datetime import datetime

class ItemBase(BaseModel):
    title: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = None
    price: float = Field(..., gt=0)
    
class ItemCreate(ItemBase):
    pass

class Item(ItemBase):
    id: int
    created_at: datetime
    
    class Config:
        orm_mode = True

Step 5: CRUD 엔드포인트 구현

생성, 조회, 수정, 삭제 기능을 구현합니다.

# app/routers/items.py
from fastapi import APIRouter, HTTPException, status
from typing import List
from ..schemas import Item, ItemCreate

router = APIRouter(
    prefix="/items",
    tags=["items"]
)

# 임시 데이터베이스 (실제로는 DB 사용)
fake_items_db = []

@router.post("/", response_model=Item, status_code=status.HTTP_201_CREATED)
async def create_item(item: ItemCreate):
    new_item = Item(
        id=len(fake_items_db) + 1,
        **item.dict(),
        created_at=datetime.now()
    )
    fake_items_db.append(new_item)
    return new_item

@router.get("/", response_model=List[Item])
async def read_items(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

@router.get("/{item_id}", response_model=Item)
async def read_item(item_id: int):
    item = next((item for item in fake_items_db if item.id == item_id), None)
    if item is None:
        raise HTTPException(status_code=404, detail="Item not found")
    return item

@router.put("/{item_id}", response_model=Item)
async def update_item(item_id: int, item_update: ItemCreate):
    item = next((item for item in fake_items_db if item.id == item_id), None)
    if item is None:
        raise HTTPException(status_code=404, detail="Item not found")
    
    updated_item = item.copy(update=item_update.dict())
    fake_items_db[item_id - 1] = updated_item
    return updated_item

@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: int):
    item = next((item for item in fake_items_db if item.id == item_id), None)
    if item is None:
        raise HTTPException(status_code=404, detail="Item not found")
    
    fake_items_db.remove(item)
    return None

Step 6: 라우터 등록 및 서버 실행

# app/main.py에 라우터 추가
from app.routers import items

app.include_router(items.router)

# 서버 실행 명령어
# uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

4. 실제 코드 예제와 설명

완전한 작동 예제

실제 사용 가능한 FastAPI 애플리케이션 예제입니다.

# complete_example.py
from fastapi import FastAPI, HTTPException, Query, Path
from pydantic import BaseModel, validator
from typing import List, Optional
from enum import Enum
import uvicorn

app = FastAPI()

class Category(str, Enum):
    ELECTRONICS = "electronics"
    CLOTHING = "clothing"
    FOOD = "food"

class Product(BaseModel):
    name: str
    price: float
    category: Category
    in_stock: bool = True
    
    @validator('price')
    def price_must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('가격은 0보다 커야 합니다')
        return v

# 임시 데이터베이스
products_db: List[Product] = [
    Product(name="노트북", price=1200000, category=Category.ELECTRONICS),
    Product(name="티셔츠", price=25000, category=Category.CLOTHING),
]

@app.get("/api/products", response_model=List[Product])
async def get_products(
    category: Optional[Category] = None,
    min_price: float = Query(0, ge=0),
    max_price: float = Query(float('inf'), ge=0)
):
    """제품 목록을 조회합니다. 카테고리와 가격 범위로 필터링 가능합니다."""
    filtered = products_db
    
    if category:
        filtered = [p for p in filtered if p.category == category]
    
    filtered = [p for p in filtered if min_price <= p.price <= max_price]
    
    return filtered

@app.post("/api/products", response_model=Product, status_code=201)
async def create_product(product: Product):
    """새로운 제품을 생성합니다."""
    products_db.append(product)
    return product

@app.get("/api/products/{product_id}", response_model=Product)
async def get_product(product_id: int = Path(..., ge=0, lt=len(products_db))):
    """특정 제품의 상세 정보를 조회합니다."""
    if product_id >= len(products_db):
        raise HTTPException(status_code=404, detail="제품을 찾을 수 없습니다")
    return products_db[product_id]

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

API 테스트 방법

서버를 실행한 후 http://localhost:8000/docs에 접속하면 자동 생성된 Swagger UI를 통해 API를 테스트할 수 있습니다. 또는 curl이나 Postman을 사용할 수 있습니다.

# curl을 이용한 테스트 예제
curl -X POST "http://localhost:8000/api/products" \
  -H "Content-Type: application/json" \
  -d '{"name":"스마트폰", "price":800000, "category":"electronics"}'

curl "http://localhost:8000/api/products?category=electronics&min_price=500000"

5. 고급 활용 방법

데이터베이스 연동

SQLAlchemy를 사용하여 실제 데이터베이스와 연동할 수 있습니다.

# database.py
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

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

인증 및 보안

JWT 토큰을 사용한 인증 시스템을 구현할 수 있습니다.

from fastapi.security import OAuth2PasswordBearer
from jose import JWTError, jwt

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.post("/token")
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    # 사용자 인증 로직
    access_token = create_access_token(data={"sub": form_data.username})
    return {"access_token": access_token, "token_type": "bearer"}

미들웨어 및 CORS 설정

from fastapi.middleware.cors import CORSMiddleware

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

비동기 데이터베이스 쿼리

비동기 처리를 통해 성능을 극대화할 수 있습니다.

from databases import Database

database = Database(DATABASE_URL)

@app.on_event("startup")
async def startup():
    await database.connect()

@app.on_event("shutdown")
async def shutdown():
    await database.disconnect()

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

이 튜토리얼을 통해 FastAPI로 REST API 만들기의 기초부터 실전 활용까지 배웠습니다. FastAPI의 강력한 기능들을 활용하면 빠르고 안정적인 API를 쉽게 구축할 수 있습니다. 다음 단계로는 실제 데이터베이스 연동, 인증 시스템 구현, 테스트 코드 작성, Docker를 이용한 배포 등을 학습하시길 추천합니다.

추가 학습 자료:

• FastAPI 공식 문서 – 가장 완벽한 학습 자료
• FastAPI GitHub 저장소 – 예제 코드 및 이슈 확인
• SQLAlchemy와 Alembic을 활용한 데이터베이스 마이그레이션
• Pytest를 이용한 API 테스트 자동화
• Docker와 Kubernetes를 활용한 프로덕션 배포

지금 바로 FastAPI로 REST API 만들기를 시작하고, 여러분만의 강력한 백엔드 서비스를 구축해보세요!