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

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

현대 웹 개발에서 FastAPI로 REST API 만들기는 필수 기술로 자리잡았습니다. FastAPI는 Python 기반의 고성능 웹 프레임워크로, 빠른 개발 속도와 자동 문서화, 타입 힌팅 지원으로 개발자들에게 사랑받고 있습니다. 이 튜토리얼에서는 FastAPI의 기본 개념부터 실제 REST API 구축까지 단계별로 학습합니다. 백엔드 개발 입문자부터 경력 개발자까지 모두에게 유용한 실전 가이드를 제공하며, 완성된 프로젝트를 통해 실무에 바로 적용 가능한 기술을 습득할 수 있습니다. Python의 async/await 문법을 활용한 비동기 처리와 자동 API 문서 생성까지 모든 것을 다룹니다.

2. 기본 개념 설명

FastAPI는 Starlette와 Pydantic을 기반으로 구축된 현대적인 Python 웹 프레임워크입니다. REST API는 Representational State Transfer의 약자로, HTTP 프로토콜을 활용해 자원(Resource)을 주고받는 아키텍처 스타일입니다. FastAPI의 주요 특징은 다음과 같습니다:

• 고성능: NodeJS, Go와 대등한 속도를 자랑하며, 비동기 처리를 네이티브로 지원합니다.
• 자동 문서화: Swagger UI와 ReDoc을 통해 API 문서가 자동 생성됩니다.
• 타입 힌팅: Python 3.6+ 타입 힌트를 활용해 데이터 검증과 직렬화를 자동으로 처리합니다.
• 직관적인 문법: 데코레이터 기반의 간결한 코드로 빠른 개발이 가능합니다.

REST API의 핵심 개념인 CRUD(Create, Read, Update, Delete) 작업을 HTTP 메서드(POST, GET, PUT, DELETE)와 매핑하여 구현합니다. FastAPI는 이러한 작업을 직관적으로 처리할 수 있는 강력한 도구를 제공합니다.

3. 단계별 구현 가이드

단계 1: 환경 설정

먼저 Python 3.7 이상이 설치되어 있는지 확인합니다. 가상 환경을 생성하고 FastAPI와 ASGI 서버인 uvicorn을 설치합니다:

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

단계 2: 프로젝트 구조 설계

효율적인 프로젝트 관리를 위해 다음과 같은 구조를 권장합니다:

myapi/
├── main.py          # 메인 애플리케이션
├── models.py        # 데이터 모델
├── routers/         # API 라우터
│   └── items.py
└── database.py      # 데이터베이스 연결

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

FastAPI로 REST API 만들기의 첫 단계는 간단한 애플리케이션을 만드는 것입니다. main.py 파일을 생성하고 기본 엔드포인트를 정의합니다. FastAPI 인스턴스를 생성하고 경로 작업 함수를 데코레이터로 등록합니다.

단계 4: 데이터 모델 정의

Pydantic 모델을 사용하여 요청과 응답 데이터의 스키마를 정의합니다. 이를 통해 자동 검증과 직렬화가 가능하며, API 문서에도 자동으로 반영됩니다. BaseModel을 상속받아 필드와 타입을 선언합니다.

단계 5: CRUD 엔드포인트 구현

각 HTTP 메서드에 맞는 경로 작업을 구현합니다:

• POST: 새 리소스 생성
• GET: 리소스 조회 (전체 목록 또는 특정 항목)
• PUT: 리소스 수정
• DELETE: 리소스 삭제

경로 매개변수, 쿼리 매개변수, 요청 본문을 활용하여 다양한 API를 설계합니다.

단계 6: 데이터베이스 연결

실전 애플리케이션에서는 데이터 영속성을 위해 데이터베이스가 필요합니다. SQLAlchemy와 같은 ORM을 사용하거나 NoSQL 데이터베이스를 연결할 수 있습니다. 의존성 주입(Dependency Injection) 패턴을 활용하여 데이터베이스 세션을 관리합니다.

단계 7: 에러 핸들링 및 검증

HTTPException을 사용하여 적절한 HTTP 상태 코드와 에러 메시지를 반환합니다. Pydantic의 검증 기능을 활용하여 입력 데이터의 유효성을 자동으로 확인합니다.

4. 실제 코드 예제와 설명

다음은 간단한 Todo 애플리케이션을 구현한 완전한 예제입니다:

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

app = FastAPI(title="Todo API")

# 데이터 모델
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_id_counter = 1

# CREATE - 새 Todo 생성
@app.post("/todos/", response_model=TodoItem, status_code=201)
def create_todo(todo: TodoItem):
    global todo_id_counter
    todo.id = todo_id_counter
    todo_id_counter += 1
    todos.append(todo)
    return todo

# READ - 전체 Todo 목록 조회
@app.get("/todos/", response_model=List[TodoItem])
def get_todos(skip: int = 0, limit: int = 10):
    return todos[skip:skip + limit]

# READ - 특정 Todo 조회
@app.get("/todos/{todo_id}", response_model=TodoItem)
def get_todo(todo_id: int):
    for todo in todos:
        if todo.id == todo_id:
            return todo
    raise HTTPException(status_code=404, detail="Todo not found")

# UPDATE - Todo 수정
@app.put("/todos/{todo_id}", response_model=TodoItem)
def update_todo(todo_id: int, todo_update: TodoUpdate):
    for todo in todos:
        if todo.id == todo_id:
            if todo_update.title is not None:
                todo.title = todo_update.title
            if todo_update.description is not None:
                todo.description = todo_update.description
            if todo_update.completed is not None:
                todo.completed = todo_update.completed
            return todo
    raise HTTPException(status_code=404, detail="Todo not found")

# DELETE - Todo 삭제
@app.delete("/todos/{todo_id}", status_code=204)
def delete_todo(todo_id: int):
    for index, todo in enumerate(todos):
        if todo.id == todo_id:
            todos.pop(index)
            return
    raise HTTPException(status_code=404, detail="Todo not found")

이 코드는 완전한 CRUD 기능을 제공합니다. 각 엔드포인트는 적절한 HTTP 메서드와 상태 코드를 사용하며, Pydantic 모델을 통해 자동 검증과 문서화가 이루어집니다. 서버를 실행하려면 다음 명령어를 사용합니다:

uvicorn main:app --reload

브라우저에서 http://localhost:8000/docs로 접속하면 Swagger UI를 통해 대화형 API 문서를 확인하고 테스트할 수 있습니다.

5. 고급 활용 방법

FastAPI로 REST API 만들기를 마스터한 후에는 다음과 같은 고급 기능을 활용할 수 있습니다:

인증 및 보안

OAuth2, JWT 토큰을 활용한 사용자 인증을 구현합니다. FastAPI의 보안 유틸리티를 사용하여 안전한 API를 구축할 수 있습니다.

미들웨어 활용

CORS 설정, 로깅, 요청 처리 시간 측정 등을 미들웨어로 구현합니다. 전역적으로 적용되는 로직을 깔끔하게 관리할 수 있습니다.

백그라운드 태스크

이메일 발송, 파일 처리 등 시간이 오래 걸리는 작업을 백그라운드에서 실행합니다. 사용자 경험을 개선하고 응답 시간을 단축할 수 있습니다.

데이터베이스 마이그레이션

Alembic을 사용하여 데이터베이스 스키마 변경을 관리합니다. 버전 관리를 통해 안전한 배포가 가능합니다.

테스트 자동화

pytest와 TestClient를 활용하여 API 엔드포인트를 자동으로 테스트합니다. 안정적인 코드 품질을 유지할 수 있습니다.

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

이 튜토리얼을 통해 FastAPI로 REST API 만들기의 기초부터 실전까지 모든 과정을 학습했습니다. FastAPI는 강력하면서도 배우기 쉬운 프레임워크로, 실무 프로젝트에 즉시 적용할 수 있습니다. 다음 단계로는 공식 문서(https://fastapi.tiangolo.com)를 참고하여 더 깊이 있는 기능을 학습하고, 실제 프로젝트를 진행해보시기 바랍니다. 데이터베이스 통합, 인증 시스템 구축, Docker를 활용한 배포 등 다양한 주제를 탐구하면서 전문성을 키워나가세요. Python 웹 개발의 새로운 표준, FastAPI와 함께 성장하시길 바랍니다!