Post

[신한 DS SW아카데미 / 2차 프로젝트] FAST API 사용해보기

Posted
By oh sun jung
9 min read
[신한 DS SW아카데미 / 2차 프로젝트] FAST API 사용해보기

🖤 2차 프로젝트에 필요한 기술을 학습해보자!

🩶 Intro

  • 이번에 데이터 기반 감정 추천 시스템 개발을 맡으며, FAST API라는 것을 처음 사용해보게 되었다.
  • 그런고로, 공식 문서를 바탕으로 간단한 사용법을 익혀보도록 하자!

🤍 Start!

공식 문서

FastAPI

FAST API란?

  • FastAPI는 현대적이고, 빠르며(고성능), 파이썬 표준 타입 힌트에 기초한 Python의 API를 빌드하기 위한 웹 서버 프레임워크이다.
  • 특징: 빠른 개발 + 빠른 실행 + 자동 문서화
    • 사용 가능한 가장 빠른 파이썬 프레임워크 중 하나라고 한다.
  • 주로 백엔드 API 서버를 만드는 데 사용한다. (웹·앱 클라이언트에서 호출하는 HTTP API)

주요 특징

  • Starlette(비동기 웹 서버 프레임워크)
    1. Starlette은 파이썬 기반의 비동기(Async) 웹 서버 프레임워크이다.
    2. 비동기 작동을 통해, 동시 처리 능력이 증가하여 효율성이 좋아짐 (기다리지 않고 다른 작업을 처리할 수 있으니까)
    3. Flask나 Django 같은 웹 프레임워크랑 비슷한 역할을 하지만, 차별점은 비동기 프로그래밍(AsyncIO)를 잘 지원한다는 점이다.
    4. FastAPI는 실제로 웹 서버 동작(라우팅, 요청/응답, 미들웨어, WebSocket, 세션, CORS 등) 부분을 Starlette에 위임한다.
  • Pydantic(데이터 검증)
    1. 파이썬에서 데이터 검증(Validation)과 데이터 모델링을 도와주는 라이브러리이다.
    2. “외부에서 들어오는 데이터(JSON, 요청 파라미터 등)가 내가 원하는 형태(타입, 형식)에 맞는지 자동으로 검사해주고, 안 맞으면 오류를 알려주는 도구”라고 할 수 있다.
    3. FastAPI는 클라이언트에서 들어온 요청 데이터를 Pydantic으로 검증한 뒤, 자동으로 파이썬 객체로 변환해준다.
    4. 이를 통해 swagger 자동 문서화가 가능하고, 데이터 유효성 검증 자동화가 가능하다.
  1. 빠른 속도
    • 내부적으로 Starlette(비동기 웹 서버 프레임워크) + Pydantic(데이터 검증) 을 조합해서 사용한다.
    • Starlette(비동기 웹 서버 프레임워크), Pydantic(데이터 검증)
    • Flask보다 빠르고, Node.js 수준 속도도 가능 (ASGI 기반)
  2. 자동 문서화
    • 서버 실행하면 /docs(Swagger UI), /redoc(ReDoc) 자동 생성된다.
    • 요청/응답 모델을 Pydantic으로 정의하면 자동으로 예쁘게 문서화된다.
  3. 타입 힌트 기반 개발
    • 함수 파라미터에 타입 힌트를 쓰면 → 입력값 자동 검증 + 문서화까지
    • 예: def hello(age: int) → age가 문자열로 들어오면 자동으로 422 오류 반환
  4. 비동기 지원
    • async def로 작성 가능하다.
      • 이를 통해 빠른 동시성 처리가 가능하다.
    • 실시간 서비스(채팅, IoT, 추천 API)에도 적합하다.
  5. Pythonic & 가벼움
    • Flask처럼 배우기 쉽지만, Django처럼 무겁지 않다.
    • 데이터 검증(Pydantic) + 경로/쿼리 파라미터 처리 모두 내장하고 있다.

실습 시작!

환경 설정

1. 파이썬 설치하고, pip version 확인하기

1
2
3
4
5
6
7

sspur@sunj-PC MINGW64 /c/developer/GitHub/5th__sinhhanDStudy/data/fastapi (main)
$ python --version
Python 3.13.7

sspur@sunj-PC MINGW64 /c/developer/GitHub/5th__sinhhanDStudy/data/fastapi (main)
$ pip --version
pip 25.2 from C:\Users\sspur\AppData\Local\Programs\Python\Python313\Lib\site-packages\pip (python 3.13)

2. fast api 설치

1
2

sspur@sunj-PC MINGW64 /c/developer/GitHub/5th__sinhhanDStudy/data/fastapi (main)
$ pip install fastapi

3. Uvicorn 설치

1
2

sspur@sunj-PC MINGW64 /c/developer/GitHub/5th__sinhhanDStudy/data/fastapi (main)
$ pip install "uvicorn[standard]"
  • 프로덕션을 위해 ASGI 서버도 필요하다.
    • 프로덕션(Production)이란? (실제 운영 환경)
      • 실제 서비스가 유저들한테 제공되는 환경 (운영 서버, 배포 서버)
      • 안정성, 보안, 성능이 중요하고 디버그 모드가 없다.
    • ASGI 서버란?
      • ASGI = Asynchronous Server Gateway Interface
      • 파이썬 웹 서버와 프레임워크(FastAPI, Django 등)를 연결해주는 표준 인터페이스이다.
      • 비동기를 지원한다.
  • 이 ASGI 서버 중 가장 많이 쓰라고 권장하는 서버가 Uvicorn이다.

예제

만들기

1
2
3
4
5
6
7
8
9
10
11
12
13

from typing import Union

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root() : 
    return {"Hello" : "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None) : 
    return {"item_id" : item_id, "q" : q}
  • q: Union[str, None] = None
    • q라는 쿼리 파라미터를 받을 건데,
    • 타입은 str 또는 None이 가능하다는 의미이다.
    • 기본값은 None이다.
    • Union[X, Y] = “이 값은 X 타입일 수도, Y 타입일 수도 있다”

서버 실행

1
2

sspur@sunj-PC MINGW64 /c/developer/GitHub/5th__sinhhanDStudy/data/fastapi (main)
$ uvicorn main:app --reload

실행 결과 확인

  • http://127.0.0.1:8000/items/5?q=somequery
    • 여기 들어가면 실행 결과 JSON을 볼 수 있다.
1

{"item_id":5,"q":"somequery"}
  • 로그 확인
    1
2
3
4
5
6
7
8
9

    $ uvicorn main:app --reload
INFO:     Will watch for changes in these directories: ['C:\\developer\\GitHub\\5th__sinhhanDStudy\\data\\fastapitest']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [9208] using WatchFiles
INFO:     Started server process [8052]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     127.0.0.1:54481 - "GET /items/5?q=somequery HTTP/1.1" 200 OK
INFO:     127.0.0.1:54481 - "GET /favicon.ico HTTP/1.1" 404 Not Found
  • 127.0.0.1:54481 - “GET /items/5?q=somequery HTTP/1.1” 200 OK
    • 다음과 같은 결과를 확인할 수 있다.

스웨거 문서 확인하기

  • http://127.0.0.1:8000/docs 을 들어가보자. image.png
  • 문서가 잘 만들어져 있는 것을 볼 수 있다. image.png
  • 동작 또한 잘 되는 것을 볼 수 있다.

예제 심화

put 요청에 있는 본문(Body) 받기

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel) : 
    name : str
    price : float
    is_offer : Union[bool, None] = None

@app.get("/")
def read_root():
    return {"Hello": "World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None):
    return {"item_id": item_id, "q": q}

@app.put("/items/{item_id}")
def update_item(item_id: int, item : Item) : 
    return {"item_name" : item.name, "item_id" : item_id}
  • 추가된 부분은 다음과 같다.
1
2
3
4
5
6
7
8

class Item(BaseModel) : 
    name : str
    price : float
    is_offer : Union[bool, None] = None

@app.put("/items/{item_id}")
def update_item(item_id: int, item : Item) : 
    return {"item_name" : item.name, "item_id" : item_id}
  • item: Item → 요청(Request) body에 JSON이 들어오면
    • Pydantic(Item 모델)이 자동으로 파싱 + 검증한다.
    • 그래서 body에 넣은 정보들을 item 객체에 자동으로 업데이트 해주는 것이다.
  • 스웨거를 실행해서 직접 body에 데이터를 실어서 보내보자.

image.png image.png

정리

  • 지금까지 학습한 것을 정리하면 다음과 같다!
    1. @app.get, @app.post, @app.put 같은 엔드포인트 만들기
    2. BaseModel로 입력 데이터 검증하기
    3. return {...} 으로 JSON 응답하기
    4. uvicorn main:app --reload 로 서버 실행하기
    5. Swagger UI (http://127.0.0.1:8000/docs) 자동 확인
project
data fast-api
This post is licensed under CC BY 4.0 by the author.