[FastAPI-①] FastAPI로 배우는 REST API 개발 입문

FastAPI로 배우는 REST API 개발 입문

REST API, 아직도 어렵게 느껴지시나요?
FastAPI를 이용하면 믿을 수 없을 만큼 쉽게 웹 API를 만들 수 있어요!

 

 

안녕하세요!

오늘부터 여러분과 함께 Python의 강력한 웹 프레임워크 FastAPI를 활용한 REST API 개발을 단계별로 배워보려고 합니다.

요즘 웹 개발에 있어서 REST API는 기본 중의 기본이죠.

다양한 시스템이 서로 데이터를 주고받기 위해 가장 많이 사용되는 방식입니다.

특히 FastAPI는 빠르고 간편하며, 자동 문서화 기능까지 갖춰져 있어 초보자도 쉽게 API를 개발할 수 있는 환상적인 도구예요.

이 블로그 시리즈에서는 REST API의 개념부터 시작해서, FastAPI 설치, Hello World 예제, 엔드포인트 추가 실습까지 하나하나 직접 구현해보며 개념과 실습을 모두 챙길 거예요.

준비되셨나요?

그럼 첫 번째 이야기, REST API와 FastAPI의 만남을 시작해볼게요! 🚀

목차

1. REST API란 무엇인가요? 2. RESTful API의 구조와 특징 3. FastAPI 프레임워크 소개 4. 개발 환경 설정과 FastAPI 설치 5. Hello FastAPI - 첫 API 만들기 6. 엔드포인트 추가 실습: 버전 정보 API 구현

 

1. REST API란 무엇인가요? 🌐

REST API는 웹에서 데이터를 주고받는 가장 표준적인 방법 중 하나입니다.

먼저 이름부터 풀어볼까요?

REST는 Representational State Transfer의 약자인데요, 말이 좀 어렵게 느껴질 수 있지만 핵심은 간단합니다.

"웹 자원을 고유한 주소(URI)로 표현하고, 그 자원에 대해 HTTP 메서드를 통해 동작을 지정한다"는 게 핵심이에요.

우리가 평소에 웹 브라우저에서 주소창에 https://example.com/users를 입력하면 "users"라는 자원(데이터 목록)에 접근하는 거잖아요?

이처럼 REST에서는 각각의 자원을 URL을 통해 표현합니다.

그리고 어떤 동작을 하고 싶은지에 따라 GET, POST, PUT, DELETE 같은 HTTP 메서드를 사용해 요청을 보냅니다.

📌 REST 아키텍처의 6가지 원칙

• 클라이언트-서버 구조 : UI와 데이터 처리를 분리해 독립적으로 발전 가능
• 무상태성 (Stateless) : 서버는 요청을 받을 때 클라이언트의 상태를 기억하지 않음
• 캐시 처리 가능 : 클라이언트는 서버 응답을 캐싱해 효율성 향상 가능
• 계층화된 시스템 : 중간 서버를 통해 보안, 로드 밸런싱 등 기능 분리
• 인터페이스 일관성 : URI 설계와 메서드 사용이 일관되게 유지되어야 함
• 코드 온 디맨드(Optional) : 서버에서 클라이언트로 스크립트 등을 전달 가능

🧩 RESTful API 설계의 예시

HTTP 메서드	URI	설명
GET	/users	모든 사용자 조회
GET	/users/123	ID가 123인 사용자 조회
POST	/users	새 사용자 등록
PUT	/users/123	ID가 123인 사용자 정보 수정
DELETE	/users/123	ID가 123인 사용자 삭제

이러한 설계 방식 덕분에 RESTful API는 명확하고 예측 가능하며 유지보수가 쉬운 구조를 가질 수 있어요.

그래서 요즘 거의 모든 서비스가 REST API 기반으로 구성되고 있죠.

그리고 이걸 Python으로 정말 쉽게 만들 수 있도록 도와주는 도구가 바로 FastAPI입니다.

 

 

2. RESTful API의 구조와 특징 🔍

RESTful API는 단순히 REST 원칙을 따르는 API 이상을 의미해요.

클라이언트와 서버 간의 소통을 효율적이고 일관되게 만들어주는 아키텍처 스타일이자 규칙의 집합이죠.

흔히들 “REST스럽다”는 표현을 쓰는데, 이는 API가 REST의 원칙을 잘 따르고 있다는 의미예요.

✅ RESTful API의 구조적 특징

1. URI를 통한 자원 표현 – 모든 자원은 고유한 URI로 식별됩니다. 예: /users, /posts/1
2. HTTP 메서드의 의미 명확화 – CRUD 작업을 각각 GET, POST, PUT, DELETE로 매핑합니다.
3. 무상태성(Stateless) – 요청은 독립적으로 처리되며, 서버는 이전 요청 상태를 저장하지 않습니다.
4. 표현(Representation)의 활용 – 클라이언트는 자원의 ‘표현’을 받으며, 보통은 JSON이나 XML 형식을 사용합니다.
5. 표준 HTTP 상태 코드 사용 – 예: 200(성공), 201(생성됨), 404(없음), 500(서버 오류)

💡 RESTful API가 주는 이점

RESTful API를 설계하면 얻게 되는 이점도 많아요.

가장 큰 장점은 바로 일관성과 가독성입니다.

 

예를 들어,

다음처럼 URI를 설계한다면 처음 보는 사람도 어떤 기능인지 대충 감이 올 거예요.

• GET /articles – 전체 글 목록 불러오기
• POST /articles – 새 글 작성
• GET /articles/3 – ID가 3인 글 조회

 

이처럼 RESTful한 API는 예측 가능하고 규칙 기반이기 때문에 협업 시에도 소통이 쉬워지고, 문서화를 따로 하지 않아도 사용할 수 있을 만큼 직관적인 경우도 많습니다.

 

❗REST API vs RESTful API – 혼동하지 마세요

간혹 REST API와 RESTful API를 같은 개념으로 쓰기도 하지만, 기술적으로는 살짝 차이가 있어요.

REST API는 단지 REST 기반 구조를 사용하는 API를 의미하고, RESTful API는 REST의 원칙을 충실히 따르는 ‘REST다운’ API를 말합니다.

즉, RESTful API는 REST API보다 좀 더 엄격한 규칙을 따른다는 뜻이에요.

 

RESTful한 구조를 유지하기 위해서는 불필요한 동사 사용을 피하고, 자원 중심으로 URI를 설계하며, HTTP 상태 코드도 적절히 활용해야 해요.

이런 기준을 지켜야만 “RESTful하다”고 말할 수 있답니다!

이제 RESTful API의 기본 철학과 구조에 대해 어느 정도 감이 오셨죠? 😉

 

다음 섹션에서는 FastAPI라는 도구를 통해 이런 RESTful API를 실제로 구현하는 방법을 배워볼 거예요.

기대되시죠?

 

 

3. FastAPI 프레임워크 소개 🚀

FastAPI는 최근 Python 웹 개발자들 사이에서 가장 주목받고 있는 비동기 기반 웹 프레임워크입니다.

Flask나 Django처럼 웹 애플리케이션을 만들 수 있으면서도,

비동기 처리, 자동 문서화, 타입 기반 유효성 검사 같은 최신 기능들을 기본으로 제공합니다.

📌 FastAPI의 핵심 특징

• 빠른 성능 – Starlette(ASGI 서버) 기반으로 구성되어 Node.js나 Go와 맞먹는 수준의 퍼포먼스를 자랑합니다.
• 타입 기반 유효성 검사 – Python의 타입 힌트를 활용해 Pydantic이 자동으로 데이터 검증 및 스키마 생성을 해줍니다.
• 자동 문서화 – OpenAPI(Swagger)와 ReDoc 기반 문서가 자동 생성되어 /docs나 /redoc 경로에서 API 테스트도 가능합니다.
• 비동기 처리 지원 – async/await 문법으로 고성능 API 서버 구현도 손쉽게 가능합니다.

⚙️ 왜 FastAPI인가요?

처음에는 Flask로도 충분하지 않나? 하는 생각이 들 수도 있어요. 저도 그랬거든요.

하지만 FastAPI를 사용해보면 정말 많은 차이를 느낄 수 있습니다.

특히 Swagger 문서 자동 생성과 비동기 처리 성능은 다른 프레임워크들이 따라오기 어려울 정도예요.

여기에 Python의 타입 힌트를 적극적으로 활용해, 코드 작성과 동시에 문서화와 유효성 검사를 자동으로 처리해주는 점이 초보자들에게도 큰 장점으로 작용합니다.

비교 항목	Flask	FastAPI
성능	중간	매우 빠름
문서화	수동 또는 확장	자동 제공 (Swagger / ReDoc)
타입 힌트 지원	선택적	강력히 활용
비동기 지원	간접적 지원	기본 제공

결론적으로 FastAPI는 빠르게 프로토타입을 만들고, 동시에 안정성과 문서화까지 챙기고 싶은 개발자에게 최적의 선택이에요.

Python을 이미 알고 있다면, FastAPI는 자연스럽고 직관적으로 배울 수 있습니다.

 

다음 글에서는 실제로 FastAPI를 설치하고 기본 개발 환경을 세팅하는 과정을 차근차근 안내해드릴게요.

이제 실습을 통해 본격적으로 시작해볼까요? 🔧

 

 

4. 개발 환경 설정과 FastAPI 설치 ⚙️

지금부터는 본격적으로 FastAPI를 개발 환경에 설치해보는 시간입니다.

FastAPI는 Python 3.7 이상에서 사용할 수 있기 때문에, 우선 Python 버전 확인부터 해볼게요.

그리고 가상환경을 만들어서 프로젝트별 의존성을 관리하는 것이 좋습니다.

🔍 Python 및 가상환경 설정

1. Python 버전 확인: python --version
2. 가상환경 생성: python -m venv venv
3. 가상환경 활성화
   • Windows: venv\Scripts\activate
   • Mac/Linux: source venv/bin/activate

가상환경이 활성화되면 프롬프트 앞에 (venv)가 붙어요.

이제 여기서 필요한 라이브러리를 설치하면 됩니다.

📦 FastAPI와 Uvicorn 설치

FastAPI는 자체적으로 웹 서버를 포함하고 있지 않기 때문에 ASGI 서버가 필요해요.

대부분의 개발자들은 Uvicorn을 사용합니다.

 

pip install fastapi
pip install "uvicorn[standard]"

 

[standard] 옵션을 포함하면 HTTP/2, WebSocket 등 다양한 기능도 함께 설치돼요.

설치가 끝나면 FastAPI 애플리케이션을 실행할 준비가 완료된 셈입니다.

📝 프로젝트 구조와 첫 파일 만들기

간단한 FastAPI 프로젝트 구조는 다음과 같아요:

• main.py – 앱 실행 파일
• venv/ – 가상환경 폴더

main.py 파일을 열고 FastAPI 기본 코드를 작성할 준비를 합니다.

다음 단계에서는 “Hello, FastAPI”라는 응답을 반환하는 아주 간단한 예제를 통해 첫 API를 직접 만들어볼 거예요.

지금까지 잘 따라오셨나요? 🧑‍💻

환경 설정만 마쳐도 절반은 완성된 셈입니다!

 

이제 직접 서버를 띄워보며 FastAPI가 어떻게 동작하는지 살펴보겠습니다.

 

 

5. Hello FastAPI - 첫 API 만들기 👋

드디어 우리가 기다리던 순간!

이제 FastAPI를 직접 실행해 보며 첫 번째 API를 만들어볼 거예요.

처음 만드는 만큼 아주 단순한 "Hello, FastAPI" 메시지를 반환하는 예제부터 시작해 보겠습니다.

📄 main.py 코드 작성

이제 main.py 파일을 열고

아래와 같이 코드를 작성해 주세요:

 

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
  return {"message": "Hello, FastAPI"}

 

이 코드에서 @app.get("/")는 루트 경로(/)에 GET 요청이 들어왔을 때 실행되는 함수입니다.

return 부분에서 반환하는 딕셔너리는 자동으로 JSON으로 변환돼서 응답으로 전송돼요.

🚀 서버 실행

이제 작성한 FastAPI 앱을 실행해볼게요.

터미널에 다음 명령어를 입력하세요:

 

uvicorn main:app --reload

 

main은 파일 이름, app은 FastAPI 객체입니다.

--reload 옵션을 붙이면 코드 변경 시 서버가 자동으로 재시작돼서 개발할 때 아주 편리하죠!

🔎 실행 결과 확인하기

• http://127.0.0.1:8000/ → {"message": "Hello, FastAPI"} 응답 확인
• http://127.0.0.1:8000/docs → Swagger 기반 API 문서 자동 생성
• http://127.0.0.1:8000/redoc → ReDoc 기반 문서 보기

정말 신기하지 않나요?

별도의 설정 없이도 이렇게 깔끔한 API 문서가 자동 생성됩니다. 🧙‍♂️

그리고 이게 FastAPI의 가장 큰 매력 중 하나예요. 작성한 API들을 테스트도 가능하니, 개발과 동시에 검증까지 가능하죠.

이제 FastAPI의 기본 구조와 실행 흐름을 이해하셨을 거예요.

다음 단계에서는 실제로 또 하나의 엔드포인트를 추가하면서 다양한 HTTP 메서드와 라우팅 개념도 함께 살펴보겠습니다.

 

 

6. 엔드포인트 추가 실습: 버전 정보 API 구현 🛠️

이전 단계에서 GET /으로 기본 응답을 반환하는 간단한 API를 만들어봤죠.

이번에는 FastAPI 앱에 새로운 엔드포인트를 하나 더 추가해보겠습니다.

예를 들어,

프로젝트의 버전 정보를 클라이언트에게 알려주는 API가 있다고 가정해볼게요.

📄 main.py에 엔드포인트 추가

@app.get("/version")
def get_version():
  return {"version": "0.1.0"}

 

이 함수는 /version 경로에 GET 요청이 들어왔을 때 버전 정보를 JSON 형식으로 반환합니다.

예를 들어,

클라이언트가 API의 버전 관리를 하고자 할 때 유용하게 사용할 수 있어요.

🔎 실행 후 테스트하기

• http://127.0.0.1:8000/version 에 접속하면 결과가 다음과 같이 나옵니다:
  {"version": "0.1.0"}
• Swagger UI 문서에서도 /version 경로가 자동으로 추가된 걸 확인할 수 있어요.

📌 엔드포인트를 추가하면서 익히는 FastAPI의 핵심

• 라우팅 – 경로(URL)마다 함수 하나씩 대응시켜 구조적으로 관리
• 함수 기반 뷰(View) – 각각의 엔드포인트는 Python 함수로 표현
• 자동 문서화 – 개발자가 문서를 별도로 작성하지 않아도 FastAPI가 Swagger 문서를 자동 생성

 

이번 실습을 통해 RESTful API의 핵심인 라우팅 설계를 직접 해보셨고, FastAPI가 얼마나 직관적이고 강력한지 직접 체험하셨을 거예요. 엔드포인트 추가는 이제 식은 죽 먹기죠?

점점 실전 API에 가까워지고 있죠? 😊

지금까지 우리는 REST API의 개념부터 FastAPI 설치, 기본 예제 구현까지 한 걸음씩 따라와 봤습니다.

처음에는 다소 낯설 수 있었던 REST 구조도, FastAPI의 직관적인 문법과 자동 문서화 덕분에 훨씬 더 쉽게 접근할 수 있었죠.

 

RESTful한 방식으로 API를 설계하면,

확장성과 유지보수성을 동시에 확보할 수 있다는 점에서 그 가치가 분명합니다.

FastAPI는 여기에 더해 빠른 속도, 간결한 코드, 뛰어난 생산성까지 갖추고 있어 Python 개발자라면 반드시 익혀야 할 도구예요.

 

다음 글에서는 POST 요청 처리와 입력 데이터 검증을 다룰 예정입니다.

본격적으로 사용자의 입력을 받아 처리하고, Pydantic을 활용한 스키마 기반 검증도 함께 배워볼 거예요.

기대되시죠? 😊

 

이 글이 도움이 되셨다면 댓글이나 공유도 환영합니다.

앞으로도 쉽고 실용적인 Python 백엔드 개발 이야기, 계속 함께해 주세요!