[REST API] RESTful API 설계 가이드

REST API는 현대 웹 서비스 개발에서 가장 널리 사용되는 아키텍처 스타일입니다. 이 글에서는 REST API의 핵심 개념부터 실제 설계 방법까지 상세히 다뤄보겠습니다.

REST API의 기본 원칙

REST(Representational State Transfer)는 다음 6가지 기본 원칙을 따릅니다:

1. Uniform Interface
2. Stateless
3. Cacheable
4. Client-Server 구조
5. Layered System
6. Code on Demand (선택사항)

RESTful한 URI 설계하기

REST API에서 가장 중요한 것은 리소스를 어떻게 정의하고 표현하느냐입니다. 다음은 실제 프로젝트에서 자주 사용되는 URI 설계 예시입니다.

# 좋은 URI 설계 예시
GET /users                 # 사용자 목록 조회
GET /users/{id}           # 특정 사용자 조회
POST /users               # 새로운 사용자 생성
PUT /users/{id}           # 사용자 정보 전체 수정
PATCH /users/{id}         # 사용자 정보 일부 수정
DELETE /users/{id}        # 사용자 삭제

# 나쁜 URI 설계 예시
GET /get-users            # 동사 사용
GET /users/get/{id}       # 중복된 동사
POST /create-user         # 불필요한 동사
DELETE /users/delete/{id} # 중복된 의미

HTTP 메서드의 올바른 사용

각 HTTP 메서드는 명확한 의미를 가지고 있으며, 이를 올바르게 사용하는 것이 중요합니다.

// HTTP 메서드별 사용 예시
GET /articles
// Response
{
    "articles": [
        { "id": 1, "title": "REST API 이해하기" },
        { "id": 2, "title": "RESTful 설계 원칙" }
    ]
}

POST /articles
// Request
{
    "title": "새로운 글",
    "content": "내용..."
}
// Response
{
    "id": 3,
    "title": "새로운 글",
    "content": "내용..."
}

PUT /articles/3
// Request
{
    "title": "수정된 글",
    "content": "수정된 내용..."
}

PATCH /articles/3
// Request
{
    "title": "제목만 수정"
}

HTTP 상태 코드의 적절한 활용

상태 코드는 API의 처리 결과를 명확하게 전달하는 중요한 수단입니다.

# FastAPI 예시
from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    if user_id <= 0:
        raise HTTPException(status_code=400, detail="잘못된 사용자 ID")

    user = await find_user(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="사용자를 찾을 수 없음")

    return user

주요 상태 코드:

• 200: 성공
• 201: 생성 성공
• 400: 잘못된 요청
• 401: 인증 필요
• 403: 권한 없음
• 404: 리소스 없음
• 500: 서버 오류

응답 데이터 구조화

일관성 있는 응답 구조는 API의 사용성을 높이는 핵심 요소입니다.

// 성공 응답의 기본 구조
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
    }
}

// 에러 응답의 기본 구조
{
    "status": "error",
    "error": {
        "code": "USER_NOT_FOUND",
        "message": "사용자를 찾을 수 없습니다.",
        "details": {
            "userId": 123
        }
    }
}

페이지네이션 구현

대량의 데이터를 다룰 때는 적절한 페이지네이션이 필수적입니다.

// 페이지네이션 요청
GET /articles?page=2&page_size=10

// 페이지네이션 응답
{
    "status": "success",
    "data": {
        "items": [...],
        "pagination": {
            "total_items": 95,
            "total_pages": 10,
            "current_page": 2,
            "page_size": 10,
            "has_next": true,
            "has_previous": true
        }
    }
}

실전 설계 체크리스트

1. 리소스 명은 명사를 사용하고 복수형을 기본으로 합니다.
2. 계층 관계는 URI에 명확히 표현합니다. (e.g., /users/{id}/posts)
3. 필터링, 정렬, 검색 조건은 쿼리 파라미터로 표현합니다.
4. API 버전 관리 전략을 수립합니다. (e.g., /v1/users)
5. HATEOAS를 고려하여 관련 리소스의 URI를 함께 제공합니다.
6. 일관된 에러 처리와 응답 형식을 유지합니다.

RESTful API를 설계할 때는 이러한 원칙들을 참고하되, 프로젝트의 특성과 요구사항에 맞게 적절히 조정하는 것이 중요합니다. 과도한 RESTful 원칙 준수보다는 실용적인 접근이 더 효과적일 수 있습니다.