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

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

FastAPI로 REST API 만들기는 현대 웹 개발에서 필수적인 스킬입니다. FastAPI는 Python 기반의 고성능 웹 프레임워크로, 빠른 개발 속도와 자동 문서화, 타입 힌팅을 통한 안정성을 제공합니다. 이 튜토리얼을 통해 여러분은 실제 프로덕션 환경에서 사용할 수 있는 REST API를 구축하는 방법을 배우게 됩니다. Node.js의 Express나 Django REST Framework와 비교했을 때, FastAPI는 더욱 직관적이고 빠른 성능을 자랑합니다. 초보자부터 중급 개발자까지 누구나 이 가이드를 따라하면 실무에 바로 적용할 수 있는 API 서버를 만들 수 있습니다.

2. 기본 개념 설명

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

FastAPI의 특징:

• 고성능: Starlette와 Pydantic 기반으로 Node.js, Go와 동등한 성능을 제공합니다.
• 자동 문서화: Swagger UI와 ReDoc이 자동으로 생성됩니다.
• 타입 검증: Python 타입 힌트를 사용하여 자동으로 데이터 검증이 이루어집니다.
• 비동기 지원: async/await 문법을 통해 비동기 처리를 간편하게 구현할 수 있습니다.
• 개발 생산성: 코드 중복을 줄이고 직관적인 문법으로 개발 속도를 높입니다.

FastAPI는 Flask의 간결함과 Django의 강력함을 결합한 프레임워크로, 마이크로서비스 아키텍처와 머신러닝 API 개발에 특히 적합합니다.

3. 단계별 구현 가이드

Step 1: 환경 설정 및 설치

먼저 Python 3.7 이상이 설치되어 있는지 확인합니다. 가상환경을 생성하여 프로젝트를 격리하는 것이 좋습니다.

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

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

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

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

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

프로젝트 폴더에 main.py 파일을 생성하고 기본적인 API를 작성합니다. FastAPI 인스턴스를 생성하고 라우트를 정의하는 것으로 시작합니다.

Step 3: 데이터 모델 정의

Pydantic 모델을 사용하여 요청과 응답의 데이터 구조를 정의합니다. 이를 통해 자동 검증과 문서화가 이루어집니다. 모델은 타입 안정성을 제공하며, 잘못된 데이터가 들어올 경우 자동으로 에러를 반환합니다.

Step 4: CRUD 작업 구현

Create(생성), Read(조회), Update(수정), Delete(삭제) 작업을 구현합니다. 실제 프로젝트에서는 데이터베이스를 사용하지만, 학습을 위해 먼저 메모리 기반으로 구현합니다.

Step 5: 경로 매개변수와 쿼리 매개변수

URL 경로에서 동적 값을 받거나, 쿼리 스트링을 통해 필터링 옵션을 제공하는 방법을 배웁니다. FastAPI는 이를 자동으로 파싱하고 검증합니다.

Step 6: 요청 본문 처리

POST, PUT 요청에서 JSON 데이터를 받아 처리하는 방법을 구현합니다. Pydantic 모델을 사용하면 복잡한 중첩 구조도 쉽게 처리할 수 있습니다.

Step 7: 응답 모델과 상태 코드

API의 응답 형식을 정의하고 적절한 HTTP 상태 코드(200, 201, 404, 422 등)를 반환하는 방법을 배웁니다. 이는 RESTful API의 표준을 따르는 중요한 부분입니다.

Step 8: 서버 실행 및 테스트

Uvicorn 서버를 실행하고 자동 생성된 Swagger 문서를 통해 API를 테스트합니다. 개발 모드에서는 코드 변경 시 자동으로 서버가 재시작됩니다.

4. 실제 코드 예제와 설명

다음은 간단한 할 일 관리 API의 완전한 예제입니다:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Optional

app = FastAPI(title="할 일 관리 API", version="1.0.0")

# 데이터 모델 정의
class TodoItem(BaseModel):
    id: Optional[int] = None
    title: str
    description: Optional[str] = None
    completed: bool = False

class TodoUpdate(BaseModel):
    title: Optional[str] = None
    description: Optional[str] = None
    completed: Optional[bool] = None

# 임시 데이터 저장소
todos = []
todo_counter = 1

# 루트 엔드포인트
@app.get("/")
async def root():
    return {"message": "FastAPI 할 일 관리 API에 오신 것을 환영합니다!"}

# 모든 할 일 조회 (GET)
@app.get("/todos", response_model=List[TodoItem])
async def get_todos(completed: Optional[bool] = None):
    if completed is None:
        return todos
    return [todo for todo in todos if todo["completed"] == completed]

# 특정 할 일 조회 (GET)
@app.get("/todos/{todo_id}", response_model=TodoItem)
async def get_todo(todo_id: int):
    for todo in todos:
        if todo["id"] == todo_id:
            return todo
    raise HTTPException(status_code=404, detail="할 일을 찾을 수 없습니다")

# 새 할 일 생성 (POST)
@app.post("/todos", response_model=TodoItem, status_code=201)
async def create_todo(todo: TodoItem):
    global todo_counter
    todo_dict = todo.dict()
    todo_dict["id"] = todo_counter
    todo_counter += 1
    todos.append(todo_dict)
    return todo_dict

# 할 일 수정 (PUT)
@app.put("/todos/{todo_id}", response_model=TodoItem)
async def update_todo(todo_id: int, todo_update: TodoUpdate):
    for idx, todo in enumerate(todos):
        if todo["id"] == todo_id:
            update_data = todo_update.dict(exclude_unset=True)
            updated_todo = {**todo, **update_data}
            todos[idx] = updated_todo
            return updated_todo
    raise HTTPException(status_code=404, detail="할 일을 찾을 수 없습니다")

# 할 일 삭제 (DELETE)
@app.delete("/todos/{todo_id}", status_code=204)
async def delete_todo(todo_id: int):
    for idx, todo in enumerate(todos):
        if todo["id"] == todo_id:
            todos.pop(idx)
            return
    raise HTTPException(status_code=404, detail="할 일을 찾을 수 없습니다")

코드 실행 방법:

# 개발 서버 실행 (자동 재시작 모드)
uvicorn main:app --reload

# 브라우저에서 다음 URL 접속
# http://localhost:8000/docs - Swagger UI
# http://localhost:8000/redoc - ReDoc

이 예제는 메모리 기반 저장소를 사용하지만, 실제 프로젝트에서는 SQLAlchemy나 MongoDB를 연결하여 영구적인 데이터 저장이 가능합니다.

5. 고급 활용 방법

데이터베이스 연동

SQLAlchemy ORM을 사용하여 PostgreSQL이나 MySQL과 연동할 수 있습니다. 비동기 데이터베이스 작업을 위해서는 databases 라이브러리나 sqlalchemy[asyncio]를 사용합니다.

pip install sqlalchemy databases asyncpg

인증 및 권한 관리

JWT(JSON Web Token)를 사용한 인증 시스템을 구축할 수 있습니다. OAuth2 플로우도 FastAPI가 기본적으로 지원합니다.

pip install python-jose[cryptography] passlib[bcrypt] python-multipart

CORS 설정

프론트엔드 애플리케이션과 통신하기 위해 CORS(Cross-Origin Resource Sharing)를 설정합니다:

from fastapi.middleware.cors import CORSMiddleware

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

백그라운드 태스크

이메일 발송이나 파일 처리 같은 시간이 걸리는 작업을 백그라운드에서 처리할 수 있습니다:

from fastapi import BackgroundTasks

@app.post("/send-notification")
async def send_notification(background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, "user@example.com")
    return {"message": "알림이 전송됩니다"}

API 버전 관리

URL 경로나 헤더를 통해 API 버전을 관리하여 하위 호환성을 유지할 수 있습니다.

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

이 튜토리얼을 통해 FastAPI로 REST API 만들기의 기초부터 실전까지 배웠습니다. FastAPI의 강력한 기능들을 활용하면 빠르고 안정적인 API 서버를 구축할 수 있습니다. 다음 단계로는 실제 데이터베이스 연동, 테스트 코드 작성, Docker 컨테이너화, CI/CD 파이프라인 구축 등을 학습하는 것을 추천합니다.

추가 학습 자료:

• 공식 문서: https://fastapi.tiangolo.com/ko/
• GitHub 저장소: FastAPI 예제 프로젝트들을 참고하세요
• FastAPI 커뮤니티: Gitter, Discord에서 개발자들과 소통하세요
• 심화 주제: WebSocket, GraphQL, 마이크로서비스 아키텍처 구현

FastAPI로 REST API 만들기를 마스터하여 여러분의 개발 커리어를 한 단계 업그레이드하세요!