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

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

FastAPI로 REST API 만들기는 현대 웹 개발에서 필수적인 기술입니다. FastAPI는 Python으로 작성된 최신 웹 프레임워크로, 빠른 성능과 직관적인 문법을 제공합니다. 이 튜토리얼에서는 환경 설정부터 실제 API 구축까지 단계별로 학습하여, 실무에서 바로 사용할 수 있는 REST API를 만드는 방법을 익히게 됩니다. FastAPI는 자동 문서 생성, 타입 검증, 비동기 처리 등의 강력한 기능을 제공하여 개발 생산성을 크게 향상시킵니다. Python 기본 문법을 알고 있다면 누구나 쉽게 따라할 수 있으며, 학습 후에는 실제 프로젝트에 적용 가능한 수준의 API 개발 능력을 갖추게 됩니다.

2. 기본 개념 설명

REST API는 Representational State Transfer의 약자로, 클라이언트와 서버 간의 통신 규약입니다. HTTP 메서드(GET, POST, PUT, DELETE)를 사용하여 리소스를 조작하며, JSON 형식으로 데이터를 주고받습니다. FastAPI는 이러한 REST API를 쉽게 구현할 수 있도록 설계된 프레임워크입니다.

FastAPI의 주요 특징은 다음과 같습니다. 첫째, Starlette 기반으로 비동기 처리를 지원하여 높은 성능을 제공합니다. 둘째, Pydantic을 활용한 자동 데이터 검증 기능으로 코드의 안정성을 높입니다. 셋째, OpenAPI(Swagger) 및 ReDoc 문서가 자동으로 생성되어 API 테스트와 문서화가 간편합니다. 넷째, Python 타입 힌트를 사용하여 코드의 가독성과 유지보수성이 뛰어납니다. 이러한 특징들은 FastAPI를 Django나 Flask와 같은 기존 프레임워크보다 더 현대적이고 효율적인 선택으로 만들어줍니다. 특히 마이크로서비스 아키텍처나 실시간 데이터 처리가 필요한 프로젝트에 적합합니다.

3. 단계별 구현 가이드

3.1 환경 설정

먼저 Python 3.7 이상이 설치되어 있는지 확인합니다. 터미널에서 다음 명령어로 가상환경을 생성하고 활성화합니다:

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

FastAPI와 ASGI 서버인 uvicorn을 설치합니다:

pip install fastapi uvicorn[standard]

3.2 기본 애플리케이션 생성

프로젝트 디렉토리를 생성하고 main.py 파일을 만듭니다. 이 파일이 API의 진입점이 됩니다. FastAPI 인스턴스를 생성하고 첫 번째 엔드포인트를 정의합니다. 데코레이터를 사용하여 HTTP 메서드와 경로를 지정하면, FastAPI가 자동으로 라우팅을 처리합니다.

3.3 데이터 모델 정의

Pydantic의 BaseModel을 상속받아 데이터 모델을 정의합니다. 이를 통해 요청 데이터의 타입 검증과 자동 문서화가 가능합니다. 예를 들어, 사용자 정보를 다루는 API라면 User 모델을 정의하여 이름, 이메일, 나이 등의 필드와 타입을 명시합니다. Pydantic은 입력 데이터가 정의된 타입과 일치하지 않으면 자동으로 에러를 반환합니다.

3.4 CRUD 엔드포인트 구현

Create, Read, Update, Delete의 기본 기능을 구현합니다. POST 메서드로 데이터를 생성하고, GET으로 조회하며, PUT으로 수정하고, DELETE로 삭제하는 엔드포인트를 각각 만듭니다. 각 엔드포인트는 경로 매개변수나 쿼리 매개변수를 통해 특정 리소스를 식별합니다. 예를 들어, /users/{user_id}는 특정 사용자를 조회하거나 수정하는 데 사용됩니다.

3.5 데이터베이스 연동

실제 프로젝트에서는 데이터를 영구 저장하기 위해 데이터베이스가 필요합니다. SQLAlchemy를 사용하여 SQLite, PostgreSQL, MySQL 등과 연동할 수 있습니다. ORM을 통해 Python 객체로 데이터베이스를 조작하며, 마이그레이션 도구인 Alembic을 함께 사용하면 스키마 변경 관리가 용이합니다.

3.6 서버 실행 및 테스트

uvicorn 명령어로 개발 서버를 실행합니다. –reload 옵션을 사용하면 코드 변경 시 자동으로 서버가 재시작됩니다. 브라우저에서 http://localhost:8000/docs에 접속하면 자동 생성된 Swagger UI를 통해 API를 테스트할 수 있습니다.

4. 실제 코드 예제와 설명

아래는 사용자 관리 API의 완전한 예제입니다:

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

app = FastAPI(title="사용자 관리 API")

# 데이터 모델 정의
class User(BaseModel):
    id: Optional[int] = None
    name: str
    email: str
    age: int

# 임시 데이터 저장소
users_db = []
user_id_counter = 1

# 모든 사용자 조회
@app.get("/users", response_model=List[User])
async def get_users():
    return users_db

# 특정 사용자 조회
@app.get("/users/{user_id}", response_model=User)
async def get_user(user_id: int):
    user = next((u for u in users_db if u["id"] == user_id), None)
    if not user:
        raise HTTPException(status_code=404, detail="사용자를 찾을 수 없습니다")
    return user

# 사용자 생성
@app.post("/users", response_model=User, status_code=201)
async def create_user(user: User):
    global user_id_counter
    user.id = user_id_counter
    user_id_counter += 1
    users_db.append(user.dict())
    return user

# 사용자 수정
@app.put("/users/{user_id}", response_model=User)
async def update_user(user_id: int, user: User):
    for idx, u in enumerate(users_db):
        if u["id"] == user_id:
            user.id = user_id
            users_db[idx] = user.dict()
            return user
    raise HTTPException(status_code=404, detail="사용자를 찾을 수 없습니다")

# 사용자 삭제
@app.delete("/users/{user_id}", status_code=204)
async def delete_user(user_id: int):
    global users_db
    users_db = [u for u in users_db if u["id"] != user_id]
    return {"message": "삭제되었습니다"}

서버를 실행하려면 다음 명령어를 사용합니다:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

이 코드는 메모리에 데이터를 저장하는 간단한 예제입니다. Pydantic 모델을 통해 데이터 검증이 자동으로 이루어지며, async 키워드를 사용하여 비동기 처리를 지원합니다. HTTPException으로 에러를 처리하고, response_model로 응답 형식을 명시합니다.

5. 고급 활용 방법

5.1 의존성 주입

FastAPI의 Depends를 사용하여 인증, 데이터베이스 세션 등 공통 로직을 재사용할 수 있습니다. 이를 통해 코드 중복을 줄이고 유지보수성을 향상시킵니다.

5.2 미들웨어 활용

CORS 설정, 로깅, 인증 등을 미들웨어로 구현하여 모든 요청에 공통 처리를 적용할 수 있습니다. CORSMiddleware를 추가하면 다른 도메인에서의 API 호출을 허용할 수 있습니다.

5.3 백그라운드 태스크

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

5.4 보안 강화

OAuth2, JWT 토큰 기반 인증을 구현하여 API 보안을 강화할 수 있습니다. FastAPI는 보안 관련 유틸리티를 내장하고 있어 쉽게 적용 가능합니다.

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

이 튜토리얼에서는 FastAPI로 REST API 만들기의 기초부터 실전 활용까지 다뤘습니다. FastAPI 공식 문서(https://fastapi.tiangolo.com)에서 더 자세한 내용을 학습할 수 있으며, Real Python, FastAPI GitHub 리포지토리의 예제들도 훌륭한 학습 자료입니다. 다음 단계로는 PostgreSQL과 같은 실제 데이터베이스 연동, Docker를 통한 배포, 테스트 코드 작성 등을 학습하시길 권장합니다. 꾸준한 실습을 통해 실무 역량을 키워나가세요!