REST API 설계 가이드 – 좋은 API를 만드는 7가지 원칙

작성자:

REST API는 웹/앱 서비스의 백본입니다. 프론트엔드와 백엔드를 연결하고, 외부 서비스와 데이터를 주고받는 핵심 인터페이스입니다. 하지만 “작동하는 API”와 “잘 설계된 API”는 다릅니다. 이 글에서 실무에서 통용되는 REST API 설계 원칙 7가지를 예시와 함께 정리합니다.

REST API 기본 개념 (30초 복습)

HTTP 메서드CRUD의미예시
GETRead데이터 조회GET /users → 사용자 목록
POSTCreate데이터 생성POST /users → 새 사용자 생성
PUTUpdate데이터 전체 수정PUT /users/1 → 사용자 1 정보 수정
PATCHPartial Update데이터 일부 수정PATCH /users/1 → 이메일만 변경
DELETEDelete데이터 삭제DELETE /users/1 → 사용자 1 삭제

원칙 1: URL은 명사, 복수형 사용

나쁜 예 ✕좋은 예 ✔이유
GET /getUsersGET /usersHTTP 메서드가 동사 역할
POST /createUserPOST /usersURL에 동사 넣지 않기
GET /userGET /users컬렉션은 복수형
DELETE /deleteUser/1DELETE /users/1메서드가 이미 “삭제”를 의미

규칙: URL은 리소스(명사)를 나타내고, HTTP 메서드가 행위를 나타냅니다.

원칙 2: 계층 구조 표현

# 사용자의 주문 목록
GET /users/1/orders

# 사용자 1의 주문 42번
GET /users/1/orders/42

# 사용자 1의 주문 42번의 상품 목록
GET /users/1/orders/42/items

규칙: 리소스 간의 관계를 URL 경로로 표현합니다. 단, 3단계 이상 깊어지면 쿼리 파라미터로 대체하는 것이 좋습니다.

원칙 3: 적절한 HTTP 상태 코드 사용

상태 코드의미사용 상황
200 OK성공GET, PUT, PATCH 성공
201 Created생성 성공POST 성공 (새 리소스 생성)
204 No Content성공, 응답 본문 없음DELETE 성공
400 Bad Request잘못된 요청필수 필드 누락, 유효성 검증 실패
401 Unauthorized인증 필요로그인 안 한 상태
403 Forbidden권한 없음로그인은 했지만 접근 권한 없음
404 Not Found리소스 없음존재하지 않는 리소스
409 Conflict충돌이미 존재하는 데이터 (중복 가입 등)
500 Internal Server Error서버 오류서버 버그, 예외 처리 안 된 에러

흔한 실수: 모든 응답에 200을 보내고, 에러를 body에만 넣는 것. 상태 코드를 정확히 사용해야 클라이언트가 적절히 처리할 수 있습니다.

원칙 4: 페이지네이션, 필터, 정렬

# 페이지네이션
GET /users?page=2&limit=20

# 필터
GET /users?city=seoul&age_min=20&age_max=30

# 정렬
GET /users?sort=created_at&order=desc

# 검색
GET /users?search=홍길동

# 조합
GET /users?city=seoul&sort=age&order=asc&page=1&limit=10

규칙: 목록 API는 반드시 페이지네이션을 제공하세요. 수만 건의 데이터를 한 번에 보내면 서버와 클라이언트 모두 부하가 걸립니다.

원칙 5: 일관된 응답 형식

// 성공 응답
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "홍길동",
        "email": "hong@mail.com"
    }
}

// 목록 응답 (페이지네이션 포함)
{
    "status": "success",
    "data": [...],
    "pagination": {
        "page": 1,
        "limit": 20,
        "total": 150,
        "total_pages": 8
    }
}

// 에러 응답
{
    "status": "error",
    "message": "이메일 형식이 올바르지 않습니다",
    "code": "INVALID_EMAIL"
}

규칙: 모든 API의 응답 형식을 통일하세요. 프론트엔드 개발자가 일관되게 처리할 수 있습니다.

원칙 6: 버전 관리

# URL에 버전 포함 (가장 일반적)
GET /api/v1/users
GET /api/v2/users

# 또는 헤더에 버전
Accept: application/vnd.myapp.v2+json

API를 변경할 때 기존 클라이언트가 깨지지 않도록 버전을 관리합니다.

원칙 7: 인증과 보안

  • HTTPS 필수: 모든 API 통신은 반드시 HTTPS로
  • JWT (JSON Web Token): 가장 일반적인 토큰 기반 인증
  • API Key: 외부 서비스 연동 시 사용
  • Rate Limiting: IP당 요청 수 제한 (DDoS 방지)
  • 입력 검증: 모든 입력값을 서버에서 재검증 (SQL Injection, XSS 방지)

API 설계 체크리스트

  • ☐ URL이 명사/복수형인가?
  • ☐ HTTP 메서드를 올바르게 사용했는가?
  • ☐ 상태 코드가 정확한가?
  • ☐ 목록 API에 페이지네이션이 있는가?
  • ☐ 응답 형식이 일관적인가?
  • ☐ 에러 응답에 명확한 메시지가 있는가?
  • ☐ HTTPS를 사용하는가?
  • ☐ 인증이 필요한 API에 인증이 적용되었는가?
  • ☐ API 문서가 작성되었는가? (Swagger/OpenAPI 추천)

마무리

좋은 REST API의 핵심: URL은 명사, 메서드는 동사, 상태 코드는 정확하게, 응답은 일관되게. 이 4가지만 지키면 누가 봐도 이해하기 쉬운 API가 됩니다. API를 사용하는 프론트엔드 개발자의 입장에서 생각하면 좋은 API가 만들어집니다.

댓글 남기기