B컷전문 | 개발과 인생의 이야기

Spring Boot에서 API 버전 관리를 URL, Header, Accept 방식으로 설계하는 전략을 소개합니다. 유지보수성과 확장성을 고려한 실전 베스트 프랙티스 포함.

---

Spring Boot 시리즈 22편 – API 버전 관리 전략: URL, Header, Accept 기반 버전 설계 Best Practice

서비스가 성장하면 API도 진화해야 합니다.
하지만 모든 사용자가 최신 API를 즉시 사용할 수는 없습니다.
기존 클라이언트는 그대로 유지하면서도 새로운 기능을 추가하려면 API 버전 관리 전략이 필수입니다.

이번 글에서는 Spring Boot 환경에서

• URL 기반
• Header 기반
• Accept(Media Type) 기반
  세 가지 주요 방식의 API 버전 관리 전략을 실무 중심으로 비교하고 적용 방법을 정리합니다.

---

📌 1. API 버전 관리가 필요한 이유

상황 문제점

API 스펙 변경	기존 사용자 요청과 충돌 발생 가능성
파라미터 추가	클라이언트 파싱 오류 가능성
응답 구조 변경	모바일 앱/외부 API 사용자 장애 발생
기능 폐기	영향도 추적 없이 일괄 제거 시 장애 위험

결론: 기존 사용자 보호 + 신규 기능 확장을 동시에 만족시켜야 함 → 버전 관리 필요

---

✅ 2. 버전 관리 전략 세 가지

1️⃣ URL 버전 방식 (가장 직관적)

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

• 장점: 명확한 버전 식별, 문서화 쉬움
• 단점: URL 변경에 따른 라우팅 관리 증가

---

2️⃣ Header 기반 버전 방식

GET /api/users
Header: X-API-VERSION: 1

• 장점: URL 변경 없이 버전 분기 가능
• 단점: 클라이언트 구현이 복잡할 수 있음, 디버깅 어려움

---

3️⃣ Accept Header (Media Type) 방식

GET /api/users
Header: Accept: application/vnd.myapp.v1+json

• 장점: REST 원칙에 부합 (콘텐츠 협상)
• 단점: 가장 복잡, 문서화 난이도 높음

---

🛠️ 3. Spring Boot에서 버전 분기 구현

1️⃣ URL 버전 방식 구현 예시

@RestController
@RequestMapping("/api/v1/users")
public class UserV1Controller {

    @GetMapping
    public UserV1Response getUser() {
        return new UserV1Response("홍길동", "user@example.com");
    }
}

@RestController
@RequestMapping("/api/v2/users")
public class UserV2Controller {

    @GetMapping
    public UserV2Response getUser() {
        return new UserV2Response("홍길동", new Email("user@example.com"));
    }
}

---

2️⃣ Header 방식 구현 (@RequestHeader 사용)

@RestController
@RequestMapping("/api/users")
public class UserHeaderVersionController {

    @GetMapping
    public Object getUser(@RequestHeader("X-API-VERSION") int version) {
        if (version == 1) {
            return new UserV1Response("홍길동", "user@example.com");
        } else {
            return new UserV2Response("홍길동", new Email("user@example.com"));
        }
    }
}

---

3️⃣ Accept Header 방식 구현

@RestController
@RequestMapping("/api/users")
public class UserAcceptVersionController {

    @GetMapping(produces = "application/vnd.myapp.v1+json")
    public UserV1Response getUserV1() {
        return new UserV1Response("홍길동", "user@example.com");
    }

    @GetMapping(produces = "application/vnd.myapp.v2+json")
    public UserV2Response getUserV2() {
        return new UserV2Response("홍길동", new Email("user@example.com"));
    }
}

---

🧠 실무 설계 전략

항목 권장 방식

모바일/웹 API	URL 버전 방식 추천 (가독성과 관리 용이)
B2B API 연동	Header 기반 권장 (경량 통신 가능)
API Gateway 활용	Accept 기반도 가능 (정교한 라우팅 지원 시)
대규모 API 플랫폼	OpenAPI 명세 자동 생성 고려 (버전별 문서화)

---

✅ 마무리 요약

항목 요약

버전 도입 이유	기존 사용자 보호 + 신규 기능 확장
버전 분기 방식	URL, Header, Accept 방식 선택 가능
Spring Boot 구현	@RequestMapping, @RequestHeader, produces로 제어 가능
실무 팁	통일된 방식 채택 + 문서화 자동화 체계 확보 필요
확장 전략	API Gateway, Swagger 통합, Deprecation 정책 동시 관리

---

📌 다음 편 예고

Spring Boot 시리즈 23편: 인증과 권한 전략 아키텍처 – OAuth2, JWT, Role 기반 접근 제어까지