REST API 설계 원칙 — 효율적인 요청/응답 구조 만들기 실무 가이드

REST API 설계 원칙 — 효율적인 요청/응답 구조 만들기 실무 가이드

현대의 대부분 웹서비스는 REST API 위에서 돌아갑니다.

백엔드와 프론트엔드, 모바일 앱이 데이터를 주고받는 방식의 중심이죠.

이번 글에서는 초보자도 이해할 수 있는 REST API의 설계 원칙부터 효율적인 요청/응답 구조, 상태 코드 설계, 그리고 실제 예시까지 실무 중심으로 정리했습니다.

 

 

1. REST API란?

REST(Representational State Transfer)는 웹 자원을 HTTP 표준으로 주고받는 아키텍처 스타일입니다.

즉, “URL로 자원을 명확히 표현하고”, “HTTP 메서드로 행위를 구분”하는 것이 핵심입니다.

💡 간단히 말하면, REST는 “무엇(URI)”과 “어떻게(HTTP Method)”를 명확히 구분한 약속입니다.

GET /users        → 사용자 목록 조회
POST /users       → 사용자 등록
GET /users/10     → 특정 사용자 조회
PUT /users/10     → 사용자 정보 수정
DELETE /users/10  → 사용자 삭제

이처럼 API 설계는 “일관성”이 가장 중요합니다.

요청/응답 규칙이 일정해야 프론트엔드와 협업이 쉬워집니다.

2. 효율적인 URL 설계 원칙

REST API의 URL은 다음 원칙을 따르는 것이 좋습니다.

• 명사 중심: /getUser 대신 /users 사용
• 복수형: /user가 아닌 /users
• 계층 표현: /users/10/orders
• 필터링은 쿼리스트링: /users?city=Seoul

💡 예시:
GET /products?category=phone&sort=price_desc
→ “핸드폰 카테고리 상품을 가격 내림차순으로 정렬” 이라는 의미가 직관적으로 전달됩니다.

3. HTTP 메서드의 역할

HTTP는 단순한 요청 방식이 아니라, 행위(Verb)를 표현하는 언어입니다.

REST 설계에서는 메서드의 의미를 명확히 구분해야 합니다.

Method	설명	예시
GET	자원 조회	GET /users
POST	자원 생성	POST /users
PUT	자원 전체 수정	PUT /users/10
PATCH	자원 일부 수정	PATCH /users/10
DELETE	자원 삭제	DELETE /users/10

💬 Tip: GET 요청에는 body를 포함하지 않습니다. POST, PUT, PATCH는 JSON 본문을 통해 데이터를 전달합니다.

4. 요청(Request)와 응답(Response) 구조

API 통신은 JSON 형식으로 주고받는 것이 일반적입니다.

Spring Boot 기준 예시는 다음과 같습니다.

// 요청(Request)
POST /api/users
{
  "name": "Hanna",
  "email": "hanna@example.com"
}

// 응답(Response)
{
  "status": "success",
  "data": {
    "id": 10,
    "name": "Hanna",
    "email": "hanna@example.com"
  }
}

💡 규칙:
- 항상 status와 data 필드를 유지
- 에러 응답에는 error.code와 error.message 포함
- 일관된 JSON 구조는 클라이언트 코드 단순화에 큰 도움을 줍니다

5. 상태 코드(Status Code)의 정확한 사용

REST API에서는 상태 코드로 결과를 명확히 표현해야 합니다.

• 200 OK: 요청 성공
• 201 Created: 새로운 자원 생성 성공
• 204 No Content: 성공했지만 반환할 데이터 없음
• 400 Bad Request: 요청 형식 오류
• 401 Unauthorized: 인증 실패
• 404 Not Found: 자원이 존재하지 않음
• 500 Internal Server Error: 서버 내부 오류

💡 실무 팁: 서버 오류(500)와 클라이언트 오류(400대)를 반드시 구분하세요.

API 응답을 볼 때, 상태 코드만 봐도 문제 원인을 80% 파악할 수 있습니다.

6. 에러 응답 설계 예시

일관성 있는 에러 구조는 유지보수를 크게 돕습니다.

{
  "status": "error",
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "해당 사용자를 찾을 수 없습니다."
  }
}

💡 추천 패턴:
- code는 영어 대문자 스네이크케이스 (USER_NOT_FOUND)
- message는 사용자 친화적 메시지
- 내부 디버깅용 세부정보는 별도 필드(logRef 등)로 분리

7. 페이징, 정렬, 검색 API 설계

데이터가 많은 경우, API는 페이징과 정렬을 지원해야 합니다.

GET /products?page=1&size=20&sort=price,desc&keyword=phone

💡 Spring Data REST 표준:
- page: 페이지 번호 (0부터 시작)
- size: 페이지당 데이터 수
- sort: 정렬 기준 (필드명,asc|desc)

결과 예시:

{
  "status": "success",
  "data": [
    {"id": 1, "name": "Galaxy S25", "price": 1300000},
    {"id": 2, "name": "iPhone 16", "price": 1500000}
  ],
  "page": {
    "current": 1,
    "totalPages": 50,
    "totalItems": 1000
  }
}

이처럼 데이터 + 메타정보를 함께 내려주는 구조가 REST API의 이상적인 형태입니다.

8. REST API 버전 관리

API는 시간이 지나면 진화합니다. 기존 클라이언트를 깨뜨리지 않으려면 버전 관리가 필요합니다.

GET /api/v1/users
GET /api/v2/users

💡 베스트 프랙티스:
- URL에 버전 명시(v1, v2)
- 급격한 스펙 변경이 없으면 동일 엔드포인트 유지
- Swagger/OpenAPI 문서로 버전별 스펙 관리

 

 

9. 성능과 보안 — 효율적 설계 포인트

REST API는 단순히 데이터를 주고받는 구조가 아니라, 서버 성능과 보안을 함께 고려해야 합니다.

• 캐싱(Cache-Control): 정적 자원은 클라이언트 캐시 활용
• 압축: gzip 압축으로 응답 크기 감소
• 토큰 기반 인증: JWT(JSON Web Token)로 stateless 인증
• 페이로드 최소화: 불필요한 필드 제거
• Rate Limiting: IP·토큰별 요청 제한으로 DDoS 예방

💡 보너스 팁:
API 응답에 X-Response-Time 헤더를 추가하면 성능 분석 시 유용합니다.

10. REST API 테스트 & 문서화

API 품질은 테스트와 문서로 완성됩니다.

Postman, cURL, Swagger(OpenAPI 3.0)을 활용하면 프론트엔드·백엔드 간의 협업 효율이 높아집니다.

// Postman 예시
GET https://api.example.com/v1/users
Headers:
  Authorization: Bearer {access_token}

💡 Swagger 문서화 예시:
- /swagger-ui.html 접속 → API 엔드포인트 자동 문서화 - 파라미터, 요청/응답 스키마, 예시 값 자동 표시

마무리

REST API 설계의 본질은 “명확함과 일관성”입니다.

불필요하게 복잡한 구조보다는, 누구나 예측 가능한 패턴을 만드는 것이 유지보수의 핵심입니다.

이제 여러분의 서버는 효율적인 DB, 안정적인 커넥션 풀, 그리고 깔끔한 REST API까지 완성됐습니다.

다음 시리즈에서는 “API 로그 추적과 모니터링 — APM으로 성능 시각화하기”를 다룰 예정입니다.

이제 서비스의 내부 흐름을 눈으로 보는 단계로 나아가 봅시다.