RESTful API 설계: 모범 사례

개발팀
2분 읽기
API백엔드웹서비스

RESTful API 설계: 모범 사례

RESTful API는 현대 웹 개발의 핵심입니다. 좋은 API 설계는 개발 효율성과 유지보수성을 크게 향상시킵니다.

RESTful 원칙

  1. 클라이언트-서버 아키텍처: 분리된 관심사
  2. 상태 비저장(Stateless): 각 요청이 독립적
  3. 균일한 인터페이스: 일관된 API 구조
  4. 캐시 가능성: 응답 캐싱 지원
  5. 계층화 시스템: 확장 가능한 구조

URI 설계 원칙

# 좋은 예
GET /api/v1/users                    # 사용자 목록 조회
GET /api/v1/users/{id}               # 특정 사용자 조회
POST /api/v1/users                   # 사용자 생성
PUT /api/v1/users/{id}               # 사용자 전체 수정
PATCH /api/v1/users/{id}             # 사용자 부분 수정
DELETE /api/v1/users/{id}            # 사용자 삭제

# 나쁜 예
GET /api/getUsers
POST /api/updateUser
GET /api/deleteUserById?id=1

HTTP 상태 코드

// 성공
200 OK          // 요청 성공
201 Created     // 리소스 생성
204 No Content  // 콘텐츠 없음

// 클라이언트 오류
400 Bad Request        // 요청 형식 오류
401 Unauthorized       // 인증 필요
403 Forbidden          // 권한 없음
404 Not Found          // 리소스 없음

// 서버 오류
500 Internal Server Error
503 Service Unavailable

요청/응답 예제

// POST /api/v1/users
{
  "name": "홍길동",
  "email": "hong@example.com",
  "age": 30
}

// 응답 (201)
{
  "id": 1,
  "name": "홍길동",
  "email": "hong@example.com",
  "age": 30,
  "createdAt": "2024-01-07T10:00:00Z"
}

에러 처리

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "요청 형식이 올바르지 않습니다.",
    "details": {
      "email": "유효한 이메일 주소를 입력하세요."
    }
  }
}

페이지네이션

GET /api/v1/users?page=1&limit=10

// 응답
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 50,
    "pages": 5
  }
}

보안 고려사항

  1. HTTPS 필수
  2. API 인증 (JWT, OAuth)
  3. Rate Limiting
  4. CORS 정책 설정
  5. 입력 검증

좋은 API 설계는 클라이언트 개발을 쉽게 하고 유지보수를 간단하게 합니다.

RESTful API 설계: 모범 사례 | 블로그