Python REST API | Flask/Django로 API 서버 만들기

들어가며

”백엔드 개발의 핵심”

REST API는 프론트엔드와 백엔드를 연결하는 표준 방식입니다.

---

1. REST API 기본

RESTful 설계 원칙

리소스 중심 설계:
GET    /api/users       - 사용자 목록
GET    /api/users/1     - 사용자 1 조회
POST   /api/users       - 사용자 생성
PUT    /api/users/1     - 사용자 1 수정
DELETE /api/users/1     - 사용자 1 삭제

---

2. Flask로 REST API

CRUD API 구현

아래 예제는 메모리에 있는 users 장바구니 리스트를 JSON으로 주고받는 미니 API입니다. GET은 목록·단건 조회, POST는 새 항목 추가, PUT/DELETE는 수정·삭제에 대응합니다. 실제 서비스에서는 이 자리를 DB와 바꿉니다.

from flask import Flask, jsonify, request

app = Flask(__name__)

users = [
    {'id': 1, 'name': '철수', 'email': '[email protected]'},
    {'id': 2, 'name': '영희', 'email': '[email protected]'}
]

# 목록 조회 (GET)
@app.route('/api/users', methods=['GET'])
def get_users():
    return jsonify({'users': users, 'count': len(users)})

# 단일 조회 (GET)
@app.route('/api/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    user = next((u for u in users if u['id'] == user_id), None)
    if user:
        return jsonify(user)
    return jsonify({'error': 'User not found'}), 404

# 생성 (POST)
@app.route('/api/users', methods=['POST'])
def create_user():
    data = request.get_json()
    
    if not data or 'name' not in data or 'email' not in data:
        return jsonify({'error': 'Invalid data'}), 400
    
    new_user = {
        'id': max(u['id'] for u in users) + 1 if users else 1,
        'name': data['name'],
        'email': data['email']
    }
    users.append(new_user)
    return jsonify(new_user), 201

# 수정 (PUT)
@app.route('/api/users/<int:user_id>', methods=['PUT'])
def update_user(user_id):
    user = next((u for u in users if u['id'] == user_id), None)
    if not user:
        return jsonify({'error': 'User not found'}), 404
    
    data = request.get_json()
    user.update(data)
    return jsonify(user)

# 삭제 (DELETE)
@app.route('/api/users/<int:user_id>', methods=['DELETE'])
def delete_user(user_id):
    global users
    users = [u for u in users if u['id'] != user_id]
    return '', 204

if __name__ == '__main__':
    app.run(debug=True)

---

3. Django REST Framework

설치

pip install djangorestframework

시리얼라이저

# blog/serializers.py
from rest_framework import serializers
from .models import Post

class PostSerializer(serializers.ModelSerializer):
    class Meta:
        model = Post
        fields = ['id', 'title', 'content', 'author', 'created_at']
        read_only_fields = ['id', 'created_at']

ViewSet

# blog/views.py
from rest_framework import viewsets
from .models import Post
from .serializers import PostSerializer

class PostViewSet(viewsets.ModelViewSet):
    queryset = Post.objects.all()
    serializer_class = PostSerializer

URL 라우팅

# blog/urls.py
from rest_framework.routers import DefaultRouter
from .views import PostViewSet

router = DefaultRouter()
router.register(r'posts', PostViewSet)

urlpatterns = router.urls

---

4. 인증과 권한

JWT 인증

pip install djangorestframework-simplejwt

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
}

# urls.py
from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
)

urlpatterns = [
    path('api/token/', TokenObtainPairView.as_view()),
    path('api/token/refresh/', TokenRefreshView.as_view()),
]

---

5. 에러 처리

커스텀 에러 응답

from flask import jsonify

@app.errorhandler(404)
def not_found(error):
    return jsonify({
        'error': 'Not Found',
        'message': '리소스를 찾을 수 없습니다'
    }), 404

@app.errorhandler(500)
def internal_error(error):
    return jsonify({
        'error': 'Internal Server Error',
        'message': '서버 오류가 발생했습니다'
    }), 500

---

6. 실전 예제

완전한 Flask API

from flask import Flask, jsonify, request
from functools import wraps

app = Flask(__name__)

# 간단한 인증
API_KEY = "secret-key-123"

def require_api_key(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        api_key = request.headers.get('X-API-Key')
        if api_key != API_KEY:
            return jsonify({'error': 'Unauthorized'}), 401
        return f(*args, **kwargs)
    return decorated

# 데이터베이스 대신 메모리 사용
posts = []

@app.route('/api/posts', methods=['GET'])
def get_posts():
    page = request.args.get('page', 1, type=int)
    per_page = request.args.get('per_page', 10, type=int)
    
    start = (page - 1) * per_page
    end = start + per_page
    
    return jsonify({
        'posts': posts[start:end],
        'page': page,
        'total': len(posts)
    })

@app.route('/api/posts', methods=['POST'])
@require_api_key
def create_post():
    data = request.get_json()
    
    required_fields = ['title', 'content']
    if not all(field in data for field in required_fields):
        return jsonify({'error': 'Missing required fields'}), 400
    
    post = {
        'id': len(posts) + 1,
        'title': data['title'],
        'content': data['content'],
        'author': data.get('author', 'Anonymous')
    }
    posts.append(post)
    
    return jsonify(post), 201

if __name__ == '__main__':
    app.run(debug=True)

---

URL 설계와 HTTP 상태 코드 (REST 관례)

REST API는 주소(URL)만 봐도 어떤 자원인지 드러나게 짓는 것이 일반적입니다. 동사를 경로에 넣기보다 명사·복수형·계층으로 자원을 표현하고, 성공·실패는 HTTP 상태 코드로 구분하면 클라이언트가 응답을 처리하기 쉽습니다.

# ✅ 명사 사용, 동사 X
GET /api/users  # O
GET /api/getUsers  # X

# ✅ 복수형 사용
GET /api/users  # O
GET /api/user  # X

# ✅ 계층 구조
GET /api/users/1/posts  # 사용자 1의 포스트

# ✅ HTTP 상태 코드
200 OK          # 성공
201 Created     # 생성 성공
400 Bad Request # 잘못된 요청
401 Unauthorized # 인증 필요
404 Not Found   # 리소스 없음
500 Server Error # 서버 오류

---

정리

핵심 요약

1. REST: HTTP + 자원 중심 설계
2. Flask: 가볍고 유연한 API 서버
3. Django REST Framework: 강력한 기능
4. 인증: JWT, API Key
5. 에러 처리: 적절한 HTTP 상태 코드

다음 단계

• 데이터베이스 연동
• 배포

---

관련 글

• Flask 기초 | Python 웹 프레임워크 시작하기