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

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

FastAPI로 REST API 만들기는 현대 웹 개발에서 가장 중요한 기술 중 하나입니다. FastAPI는 Python 3.7+의 타입 힌트를 기반으로 하는 현대적이고 빠른 웹 프레임워크로, Flask나 Django보다 훨씬 빠른 성능을 자랑합니다. 이 튜토리얼을 통해 여러분은 실제 프로덕션 환경에서 사용할 수 있는 REST API를 처음부터 끝까지 구축하는 방법을 배우게 됩니다. 자동 API 문서 생성, 데이터 유효성 검증, 비동기 처리 등 FastAPI의 강력한 기능들을 실습을 통해 마스터할 수 있습니다. 백엔드 개발자로 성장하고 싶거나, 마이크로서비스 아키텍처를 구축하려는 개발자라면 반드시 알아야 할 필수 기술입니다.

2. 기본 개념 설명

REST API는 Representational State Transfer의 약자로, HTTP 프로토콜을 통해 데이터를 주고받는 아키텍처 스타일입니다. GET, POST, PUT, DELETE 등의 HTTP 메서드를 사용하여 리소스를 조작하며, JSON 형식으로 데이터를 교환합니다.

FastAPI는 Starlette(웹 처리)와 Pydantic(데이터 검증)을 기반으로 구축된 고성능 프레임워크입니다. 주요 특징은 다음과 같습니다:

• 빠른 성능: NodeJS 및 Go와 비슷한 수준의 성능 제공
• 자동 문서화: Swagger UI와 ReDoc을 자동으로 생성
• 타입 안정성: Python 타입 힌트를 활용한 자동 검증
• 비동기 지원: async/await를 통한 효율적인 비동기 처리
• 적은 버그: 타입 체크로 인한 개발자 오류 40% 감소

이러한 특징들 덕분에 FastAPI는 Netflix, Uber, Microsoft 등 글로벌 기업들이 채택하고 있으며, GitHub 스타 수가 70,000개 이상인 인기 프레임워크입니다.

3. 단계별 구현 가이드

Step 1: 환경 설정

먼저 Python 3.7 이상이 설치되어 있는지 확인하고, 가상환경을 생성합니다:

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install fastapi uvicorn[standard] pydantic

fastapi는 프레임워크 본체이고, uvicorn은 ASGI 서버로 FastAPI 애플리케이션을 실행하는 데 필요합니다.

Step 2: 프로젝트 구조 설계

효율적인 프로젝트를 위한 디렉토리 구조를 생성합니다:

my_api/
├── main.py          # 메인 애플리케이션
├── models.py        # 데이터 모델
├── routers/         # API 라우터
│   └── items.py
├── database.py      # 데이터베이스 설정
└── requirements.txt # 의존성 목록

Step 3: 첫 번째 API 엔드포인트 생성

FastAPI로 REST API 만들기의 가장 기본이 되는 Hello World 엔드포인트를 생성합니다. main.py 파일을 만들고 다음과 같이 작성합니다:

from fastapi import FastAPI

app = FastAPI(title="My REST API", version="1.0.0")

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

서버를 실행하려면 터미널에서 다음 명령어를 입력합니다:

uvicorn main:app --reload

--reload 옵션은 코드 변경 시 자동으로 서버를 재시작합니다. 브라우저에서 http://localhost:8000에 접속하면 결과를 확인할 수 있고, http://localhost:8000/docs에서 자동 생성된 API 문서를 볼 수 있습니다.

Step 4: 데이터 모델 정의

Pydantic을 사용하여 요청/응답 데이터의 구조를 정의합니다. models.py를 생성합니다:

from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    id: Optional[int] = None
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = Field(None, max_length=500)
    price: float = Field(..., gt=0)
    in_stock: bool = True
    
    class Config:
        json_schema_extra = {
            "example": {
                "name": "노트북",
                "description": "고성능 개발용 노트북",
                "price": 1500000,
                "in_stock": True
            }
        }

Step 5: CRUD 엔드포인트 구현

이제 실제 데이터를 처리하는 CREATE, READ, UPDATE, DELETE 작업을 구현합니다. 간단한 인메모리 데이터베이스를 사용하여 main.py를 확장합니다.

4. 실제 코드 예제와 설명

완전한 CRUD API 구현 예제입니다:

from fastapi import FastAPI, HTTPException, status
from models import Item
from typing import List

app = FastAPI()

# 임시 데이터 저장소
items_db = {}
item_id_counter = 1

@app.post("/items/", response_model=Item, status_code=status.HTTP_201_CREATED)
async def create_item(item: Item):
    """새로운 아이템을 생성합니다."""
    global item_id_counter
    item.id = item_id_counter
    items_db[item_id_counter] = item
    item_id_counter += 1
    return item

@app.get("/items/", response_model=List[Item])
async def get_items(skip: int = 0, limit: int = 10):
    """모든 아이템을 조회합니다. 페이징 지원."""
    items = list(items_db.values())
    return items[skip : skip + limit]

@app.get("/items/{item_id}", response_model=Item)
async def get_item(item_id: int):
    """특정 아이템을 조회합니다."""
    if item_id not in items_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Item with id {item_id} not found"
        )
    return items_db[item_id]

@app.put("/items/{item_id}", response_model=Item)
async def update_item(item_id: int, item: Item):
    """아이템을 수정합니다."""
    if item_id not in items_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Item with id {item_id} not found"
        )
    item.id = item_id
    items_db[item_id] = item
    return item

@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: int):
    """아이템을 삭제합니다."""
    if item_id not in items_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Item with id {item_id} not found"
        )
    del items_db[item_id]
    return None

코드 설명:

• response_model: 응답 데이터의 타입을 지정하여 자동 검증 및 직렬화
• status_code: HTTP 상태 코드를 명시적으로 지정
• HTTPException: 에러 상황에서 적절한 HTTP 응답 반환
• 경로 매개변수({item_id}): URL에서 동적 값을 추출
• 쿼리 매개변수(skip, limit): 페이징 구현

이 코드를 실행하고 http://localhost:8000/docs에 접속하면 모든 엔드포인트를 직접 테스트할 수 있는 대화형 문서가 자동으로 생성됩니다.

5. 고급 활용 방법

의존성 주입 (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=403, detail="Invalid token")
    return x_token

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

데이터베이스 연동

FastAPI로 REST API 만들기에서 실제 데이터베이스를 사용하려면 SQLAlchemy나 Tortoise ORM을 활용할 수 있습니다:

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "sqlite:///./test.db"
engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(bind=engine)

미들웨어와 CORS 설정

프론트엔드와 통신하기 위한 CORS 설정:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

비동기 처리

데이터베이스나 외부 API 호출 시 비동기 처리로 성능을 극대화할 수 있습니다:

import httpx

@app.get("/external-data/")
async def fetch_external_data():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.example.com/data")
        return response.json()

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

이 튜토리얼을 통해 FastAPI로 REST API 만들기의 핵심 개념과 실전 구현 방법을 배웠습니다. FastAPI의 자동 문서화, 타입 안정성, 빠른 성능은 현대 웹 개발에서 큰 장점입니다.

다음 단계로 학습할 내용:

• JWT 기반 인증 시스템 구축
• PostgreSQL/MongoDB와 같은 실제 데이터베이스 연동
• Docker를 이용한 컨테이너화
• 테스트 코드 작성 (pytest 활용)
• 배포 전략 (AWS, Heroku, Google Cloud)

추가 학습 자료:

• 공식 문서: https://fastapi.tiangolo.com
• FastAPI GitHub: https://github.com/tiangolo/fastapi
• Real Python FastAPI 튜토리얼
• TestDriven.io FastAPI 코스

이제 여러분만의 REST API를 만들어보세요. 실습을 통해 경험을 쌓는 것이 가장 빠른 학습 방법입니다!