파이썬 REST API 개발 및 활용 완벽 가이드
웹 브라우저 말고도,
모바일 앱이나 외부 시스템에서도 우리 Flask 게시판을 사용할 수 있다면 얼마나 좋을까요?
그 해답은 바로 REST API입니다!
안녕하세요! 😊
Flask 기반 웹 게시판 프로젝트 여섯째 날입니다.
오늘은 웹 프론트엔드만이 아닌, 외부 클라이언트에서도 사용할 수 있는 REST API 개발을 함께 배워보려고 해요.
예를 들어,
우리가 만든 게시판 기능을 모바일 앱이나 다른 백엔드 서비스에서도 활용하고 싶다면 어떻게 해야 할까요?
그 해답은 바로 Flask를 이용한 RESTful API 구축이에요.
이번 시간에는 REST의 기본 개념부터 시작해 Flask에서 JSON 데이터를 주고받는 API 만들기,
그리고 게시판 CRUD API를 직접 구현해보는 실습까지 차근차근 진행할게요.
어렵지 않아요. 이미 우리가 만든 게시판 로직을 바탕으로 하니까 훨씬 수월하게 느껴질 거예요.
그럼 시작해볼까요?
목차
1. RESTful API란 무엇인가요? 🤔
요즘 웹 개발에서 REST API라는 말을 자주 들어보셨을 거예요.
그만큼 백엔드 서비스를 설계할 때 꼭 알아야 할 중요한 개념이죠.
하지만 처음 들었을 땐 뭔가 복잡하고 어려워 보일 수 있어요.
그래서 이번에는 RESTful API의 핵심 개념을 쉽고 간단하게 정리해드릴게요!
REST의 핵심 개념은?
- Resource(자원): REST는 웹의 모든 것을 자원으로 봅니다. 예를 들어 게시글(post), 사용자(user) 같은 것이죠.
- URI(Uniform Resource Identifier): 자원을 식별하는 주소입니다. 예:
/api/posts - HTTP 메서드: 자원에 대한 동작을 정의합니다. 예: GET(조회), POST(생성), PUT/PATCH(수정), DELETE(삭제)
REST API는 왜 이렇게 인기가 많을까요?
REST API가 널리 쓰이는 이유는 간단해요.
간결하고 직관적인 구조 덕분이죠.
복잡한 규약 없이 HTTP의 기본 동작만으로 다양한 클라이언트와 쉽게 통신할 수 있으니까요.
또한, REST API는 다음과 같은 특징들을 가지고 있어요:
- 🎯 Stateless(무상태성): 각 요청은 독립적이며, 서버는 이전 요청의 상태를 저장하지 않아요.
- 🔄 Cacheable: 응답은 캐싱이 가능하므로 성능을 높일 수 있어요.
- 🧩 Uniform Interface: 표준화된 인터페이스 덕분에 다양한 플랫폼에서 사용할 수 있어요.
RESTful API 설계시 고려사항은? 🧐
RESTful하게 API를 설계하기 위해 지켜야 할 몇 가지 규칙이 있어요.
특히 초보자들이 자주 놓치는 부분들을 짚어볼게요.
- URL은 복수형 명사로: 예를 들어 게시글이면
/api/posts와 같이 작성하는 것이 좋습니다. - HTTP 상태 코드 정확히 사용: 예를 들어, 성공은 200, 생성은 201, 오류는 400 또는 404 등으로 클라이언트에게 명확히 알려줘야 해요.
- JSON 응답은 일관성 있게: 예를 들어 항상
{"id": 1, "title": "...", "content": "..."}와 같은 형식 유지
REST API는 단순히 엔드포인트만 만든다고 되는 게 아니라,
일관성과 예측 가능성을 고려해 설계해야 클라이언트가 편하게 쓸 수 있어요.
이게 바로 진짜 백엔드 개발자의 센스겠죠? 😉
2. Flask에서 REST API 만들기 🔧
자, 이제 본격적으로 Flask로 REST API를 만들어볼까요?
사실 Flask에서는 별도의 라이브러리 없이도 API를 쉽게 만들 수 있어요.
jsonify() 함수와 request.get_json() 메서드만 잘 활용하면 되거든요.
기본 API 예제
가장 기본적인 API는 이렇습니다.
“/api/hello”에 GET 요청을 보내면 JSON 형식으로 인사 메시지를 돌려주는 간단한 코드예요.
from flask import Flask, jsonify
app = Flask(__name__)
@app.route("/api/hello", methods=["GET"])
def hello_api():
return jsonify(message="안녕하세요! 여기는 Flask REST API입니다.")
이렇게 간단한 코드만으로도 API가 완성돼요.
응답은 자동으로 Content-Type: application/json을 포함하므로 별도 설정도 필요 없답니다.
POST 요청 처리 - 클라이언트로부터 JSON 받기
POST 요청은 클라이언트가 서버에 데이터를 보낼 때 사용합니다.
아래처럼 request.get_json()으로 JSON 데이터를 받아 처리할 수 있어요.
from flask import request
@app.route("/api/echo", methods=["POST"])
def echo_api():
data = request.get_json()
name = data.get("name", "익명")
return jsonify(message=f"{name}님, 안녕하세요!")
- request.get_json(): JSON 데이터를 받아서 Python dict로 변환해줘요.
- jsonify(): dict를 JSON으로 변환해서 응답해줍니다.
💡 확장 라이브러리는 쓸까 말까?
Flask는 기본 기능만으로도 API 작성이 가능하지만, 더 복잡한 구조나 반복을 줄이려면 Flask-RESTful 같은 확장을 쓸 수도 있어요.
하지만 지금은 기초 개념을 제대로 익히는 것이 중요하므로, 확장 없이 직접 구현해볼게요.
즉, JSON 처리에 필요한 최소한의 도구만으로도 강력한 API를 만들 수 있다는 점!
Flask의 가장 큰 매력이자 초보자에게 추천하는 이유이기도 해요.
3. JSON 응답 및 요청 처리 방식 📦
REST API에서 데이터를 주고받을 때 가장 흔히 사용하는 형식이 바로 JSON입니다.
Flask에서는 JSON 처리가 매우 간단하면서도 직관적이에요.
이번엔 JSON 응답을 어떻게 만들고, 클라이언트의 JSON 요청 데이터를 어떻게 처리하는지를 정리해볼게요.
1️⃣ JSON 응답 만들기
HTML을 반환하던 일반 웹 뷰와 달리,
API에서는 Python의 딕셔너리 데이터를 JSON 문자열로 변환해서 반환합니다.
Flask에서는 jsonify()를 사용하면 딕셔너리를 자동으로 JSON 형식으로 바꿔주고,
Content-Type도 application/json으로 지정해줍니다.
from flask import jsonify
@app.route("/api/greet")
def greet():
return jsonify({
"status": "success",
"message": "API가 정상 작동 중입니다."
})
- jsonify()는 자동으로
application/jsonMIME 타입과200 OK상태 코드를 설정합니다.
2️⃣ 클라이언트 JSON 요청 처리하기
클라이언트가 보내는 JSON 데이터를 받으려면 request.get_json() 메서드를 사용합니다.
이때 Content-Type이 application/json으로 설정되어 있어야 해요.
from flask import request
@app.route("/api/submit", methods=["POST"])
def submit_data():
data = request.get_json()
name = data.get("name")
age = data.get("age")
if not name or not age:
return jsonify(error="Missing fields"), 400
return jsonify(message=f"{name}님({age}세), 데이터가 잘 수신되었습니다.")
get_json()을 통해 클라이언트의 JSON 요청을 dict로 파싱하고, 데이터 유효성 검사까지 함께 처리할 수 있어요.
3️⃣ 잘못된 요청 처리하기
API는 언제나 올바르지 않은 요청을 고려해야 합니다.
예를 들어
JSON 필드가 빠졌거나 잘못된 값이 들어오면, 클라이언트에게 명확한 메시지와 함께 400 Bad Request를 반환해야 하죠.
이런 식으로 API의 응답 일관성을 유지하는 것이 사용자 경험을 높이는 핵심 포인트입니다!
🔓 참고: CORS(Cross-Origin Resource Sharing)
프론트엔드가 다른 도메인(예: React 앱)에서 API를 호출할 경우 CORS 문제가 발생할 수 있어요.
이럴 땐 Flask-CORS 확장을 사용하면 아주 쉽게 해결할 수 있습니다.
# 설치
pip install flask-cors
# 사용 예
from flask_cors import CORS
app = Flask(__name__)
CORS(app)
4. 게시판 CRUD API 설계 및 구현 📝
이제 본격적으로 게시판 기능을 REST API 형태로 구현해볼 차례입니다.
이전까지는 HTML 페이지를 렌더링해 사용자에게 보여주는 방식이었다면,
이번에는 데이터를 JSON으로 주고받는 API 방식으로 확장합니다.
같은 기능이지만 'API형 백엔드'로 구현한다는 점에서 의미가 커요!
📌 API 엔드포인트 설계
| Method | URL | 설명 |
|---|---|---|
| POST | /api/posts | 게시글 생성 |
| GET | /api/posts | 게시글 목록 조회 |
| GET | /api/posts/<id> | 게시글 상세 조회 |
| PUT | /api/posts/<id> | 게시글 수정 |
| DELETE | /api/posts/<id> | 게시글 삭제 |
🔨 주요 기능별 구현 예제
1. 게시글 생성 - POST /api/posts
@app.route("/api/posts", methods=["POST"])
def create_post():
data = request.get_json()
title = data.get("title")
content = data.get("content")
if not title or not content:
return jsonify(error="필수 입력값 누락"), 400
new_post = Post(title=title, content=content)
db.session.add(new_post)
db.session.commit()
return jsonify(post_id=new_post.id), 201
2. 게시글 목록 - GET /api/posts
@app.route("/api/posts", methods=["GET"])
def get_posts():
posts = Post.query.order_by(Post.id.desc()).all()
result = [post.to_dict() for post in posts]
return jsonify(posts=result)
※ to_dict()는 모델 클래스에 미리 정의해두어야 합니다.
예: return {"id": self.id, "title": self.title, ...}
3. 게시글 상세조회 - GET /api/posts/<id>
@app.route("/api/posts/<int:post_id>", methods=["GET"])
def get_post(post_id):
post = Post.query.get(post_id)
if not post:
return jsonify(error="존재하지 않는 게시글입니다."), 404
return jsonify(post=post.to_dict())
4. 게시글 수정 - PUT /api/posts/<id>
@app.route("/api/posts/<int:post_id>", methods=["PUT"])
def update_post(post_id):
post = Post.query.get(post_id)
if not post:
return jsonify(error="해당 게시글 없음"), 404
data = request.get_json()
post.title = data.get("title", post.title)
post.content = data.get("content", post.content)
db.session.commit()
return jsonify(message="수정 완료", post=post.to_dict())
5. 게시글 삭제 - DELETE /api/posts/<id>
@app.route("/api/posts/<int:post_id>", methods=["DELETE"])
def delete_post(post_id):
post = Post.query.get(post_id)
if not post:
return jsonify(error="해당 게시글 없음"), 404
db.session.delete(post)
db.session.commit()
return jsonify(message="삭제 완료")
5. 실습: API 테스트와 사용 예시 🧪
API를 만들었으면 이제는 잘 작동하는지 테스트해봐야겠죠?
우리가 만든 REST API는 브라우저에서는 GET 요청 정도만 직접 확인할 수 있어요.
하지만 POST, PUT, DELETE 같은 요청은 curl이나 Postman 같은 도구로 테스트하는 게 일반적입니다.
🖥 curl 명령어로 API 테스트
- GET 요청 - 게시글 목록 확인:
curl -X GET http://localhost:5000/api/posts - POST 요청 - 새 게시글 생성:
curl -X POST -H "Content-Type: application/json" -d '{"title":"첫 글", "content":"안녕하세요"}' http://localhost:5000/api/posts
🧪 Postman 사용 팁
Postman은 GUI 기반의 API 테스트 도구예요.
HTTP 메서드 선택, 요청 바디 JSON 입력, 응답 확인을 아주 편리하게 할 수 있습니다.
- Postman 실행 후 새 요청(Request) 생성
- Method:
POST, URL:http://localhost:5000/api/posts - Body 탭 → raw → JSON 선택 후 아래 내용 입력:
{ "title": "Postman 테스트", "content": "이건 Postman에서 보낸 글이에요." }- Send 버튼 클릭 → 응답 확인!
✅ 예외 케이스 테스트하기
- 존재하지 않는 게시글을 조회:
GET /api/posts/99999→ 404 응답 확인 - 필수 필드 누락 POST 요청 보내기 →
400 Bad Request응답 확인
테스트를 반복하면서 우리 API가 얼마나 잘 짜여져 있는지 실감하게 되실 거예요.
오류 메시지도 일관성 있게 만들었다면 더더욱 멋지죠! 😉
6. 다양한 클라이언트와의 연동 시나리오 📱
지금까지 우리는 Flask 기반 게시판 API를 설계하고 구현하고, 테스트까지 마쳤어요.
이제는 다양한 클라이언트에서 이 API를 어떻게 활용할 수 있을지에 대해 살펴보는 시간입니다.
단순히 웹 브라우저뿐 아니라 모바일 앱, 프론트엔드 자바스크립트, 다른 백엔드 서비스 등과 연동되는 시나리오를 떠올려볼 수 있어요.
🧩 JavaScript에서 AJAX로 API 호출
가장 흔한 연동 방식은 웹 페이지에서 자바스크립트를 이용해 AJAX 방식으로 API를 호출하는 거예요.
예를 들어, HTML 페이지에서 아래처럼 Javascript의 fetch API를 사용할 수 있죠.
fetch("/api/posts")
.then(response => response.json())
.then(data => {
console.log("게시글 목록:", data.posts);
});
이렇게 하면 서버에서 JSON으로 반환한 게시글 목록을 자바스크립트에서 받아와 자유롭게 화면에 뿌릴 수 있어요.
📱 Flutter, React Native 같은 모바일 앱에서 연동
모바일 앱도 마찬가지예요.
백엔드에서 제공한 REST API를 HTTP 통신 모듈 (예: Flutter의 http 패키지, React Native의 axios)로 호출하면 앱에서도 동일하게 게시글을 CRUD할 수 있답니다.
- Flutter에서는
http.post(),http.get()으로 JSON 데이터를 보내고 받아요. - React Native에서는
axios.post(),axios.get()방식으로 쉽게 연동 가능해요.
🔗 다른 백엔드 시스템과의 연동
우리가 만든 Flask API는 마이크로서비스 구조에서도 활용할 수 있어요.
예를 들어,
사용자 인증은 Django가 담당하고, 게시판 기능은 Flask가 담당하는 식으로 서비스별 역할을 분리해서 통신하는 구조를 만들 수도 있어요.
🚀 실전 팁
- API 응답 형식은 항상 일관되게 유지하세요. (예: {"status": "success", "data": ...})
- 클라이언트가 다양한 환경에서 호출하는 만큼, CORS 설정은 반드시 고려해야 해요.
- API 문서화도 중요합니다! Swagger UI 또는 Postman Collection 등 활용해보세요.
이제 우리가 만든 Flask 백엔드는 웹, 앱, 서버 어디서든 활용 가능한 멋진 API 서비스가 되었어요.
여기까지 잘 따라오셨다면 이미 여러분은 초보 탈출 성공! 🎉
마무리 ✨
이번 여섯째 날 학습에서는 우리가 만든 게시판 웹 애플리케이션을 RESTful API로 확장하는 방법을 익혔습니다.
단순히 기능을 구현하는 것에서 한 걸음 더 나아가, 다양한 클라이언트와 연동 가능한 백엔드 서비스로 발전시키는 데 성공했어요.
REST API의 핵심 개념부터 Flask에서의 실제 구현, JSON 데이터 처리 방식, 그리고 Postman과 curl을 통한 실전 테스트까지 모든 과정을 실습하며 직접 체험해보셨을 텐데요, 어떠셨나요?
좀 더 현업 백엔드 개발자처럼 느껴지지 않으셨나요?
이제 여러분의 Flask 웹 서비스는 단지 브라우저에서만 동작하는 게 아니라, 앱, JS 프론트, 외부 시스템 등 어디에서든 자유롭게 사용할 수 있는 API 플랫폼이 된 거예요.
다음 시간에는 이 API를 어떻게 응용할 수 있을지, 또 성능 향상이나 인증 같은 고급 기능도 배워보면 좋겠죠?
혹시 아직 익숙하지 않은 부분이 있다면, 실습한 코드를 천천히 다시 보면서 정리해보세요.
반복이 최고의 선생님이니까요 😊
다음 단계에서 또 만나요!
'Python > Python 웹프로그래밍' 카테고리의 다른 글
| [Flask-⑤] 파이썬과 Flask로 만드는 게시판 CRUD 완벽 가이드 (0) | 2025.04.15 |
|---|---|
| [Flask-④] 파이썬 ORM과 데이터베이스 연동 (SQLAlchemy) (0) | 2025.04.15 |
| [Flask-③] 파이썬 Flask 애플리케이션 구조화 (Blueprint)와 에러 핸들링 (0) | 2025.04.15 |
| [Flask-②] 파이썬 Flask 라우팅, 요청/응답 처리와 템플릿 렌더링 (1) | 2025.04.15 |
| [Flask-①] 파이썬 Flask 기본 개념과 개발 환경 설정 (0) | 2025.04.15 |
