Spring Boot REST API 버전 관리 설계

소개

API는 서비스 발전에 따라 변한다. 그러므로 버전 관리는 안정적인 클라이언트 경험과 개발 효율을 동시에 확보하는 핵심이다. 본문에서는 Spring Boot를 기준으로 REST API 설계 원칙과 대표적인 버전 관리 기법, 구현 예제, 마이그레이션 전략을 실무 관점에서 정리한다.

버전 관리가 필요한 이유

버전 관리는 다음 목적을 가진다.

• 기존 클라이언트 호환성 유지
• 새 기능 도입 시 영향 범위 제한
• 점진적 마이그레이션과 롤백 용이성 확보

주요 버전 관리 전략

대표적인 방법은 URI, 헤더, 미디어 타입, 쿼리 파라미터 방식이다. 각 방식의 장단점과 사용 시점을 이해하면 설계 선택에 도움이 된다.

1. URI 버전링 (/v1/, /v2/)

가장 직관적이다. 캐시와 라우팅에서 처리하기 쉽다. 하지만 URI가 리소스의 의미와 결을 섞는 단점이 있다.

2. 커스텀 헤더 (X-API-VERSION)

URI를 오염시키지 않고 버전을 분리한다. 보안 장비나 프록시에서 헤더를 조작할 수 있어 주의가 필요하다.

3. Accept 헤더와 미디어 타입 (Content Negotiation)

표준에 가깝다. 클라이언트가 원하는 미디어 타입으로 버전을 선택한다. 구현 복잡도가 다소 높다.

4. 쿼리 파라미터 (?version=1)

간단하지만 캐싱이나 검색 엔진이 쿼리를 무시할 수 있어 권장 사례는 아니다.

설계 원칙

• 명확성: 버전이 무엇을 바꾸는지 문서화
• 호환성 우선: 가능한 한 하위 호환성 유지
• 점진적 이행: 새 버전 병행 운영 후 단계적 전환
• 테스트 자동화: 버전별 통합·회귀 테스트 확보

Spring Boot 구현 예제

아래는 URI 기반과 헤더 기반 두 가지 간단한 구현 예이다. 실제 프로젝트에서는 공통 응답 포맷, 예외 처리, DTO 매핑을 적절히 분리한다.

1) URI 기반 컨트롤러 예

package com.example.api.v1;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {
    @GetMapping
    public UserResponse getUser() {
        return new UserResponse("hong", 30);
    }
}

package com.example.api.v2;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 {
    @GetMapping
    public UserResponseV2 getUser() {
        return new UserResponseV2("hong", 30, "seoul");
    }
}

2) 헤더 기반 컨트롤러 예

package com.example.api;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
public class UserController {
    @GetMapping
    public Object getUser(@RequestHeader(value = "X-API-VERSION", required = false) String version) {
        if ("2".equals(version)) {
            return new UserResponseV2("hong", 30, "seoul");
        }
        return new UserResponse("hong", 30);
    }
}

버전 관리 및 배포 전략

버전은 한 번에 완전히 교체하기보다 병행 운영을 권장한다. 단계는 다음과 같다.

• 새 버전 개발 및 내부 검증
• 스테이징에서 통합 테스트 수행
• 일부 트래픽을 신규 버전으로 라우팅(카나리 배포)
• 모니터링으로 안정성 확인 후 전체 전환
• 레거시 버전은 Deprecation 정책과 함께 일정 기간 유지

테스트와 문서화

버전별로 자동화된 계약 테스트와 통합 테스트를 마련한다. OpenAPI(Swagger)로 각 버전의 스펙을 분리해 문서화하면 클라이언트 혼선을 줄인다.

운영 시 고려사항

• 로그에 버전 정보 기록으로 문제 추적 용이
• 모니터링 지표는 버전별로 분리 집계
• 호환성 문제 발생 시 빠른 롤백 경로 확보

권장 패턴 요약

간단한 서비스나 빠른 시작에는 URI 버전링이 적합하다. API의 진화가 잦고 미세한 호환성 제어가 필요하면 헤더 또는 미디어 타입 방식을 고려한다. 어떤 방식을 선택하든 문서화, 테스트, 모니터링을 우선시하면 안정적인 운영이 가능하다.

맺음말

버전 관리는 기술적 선택과 운영 정책의 결합이다. Spring Boot에서 제공하는 유연한 라우팅과 빈 설정을 활용하면 무중단 배포와 호환성 확보가 용이하다. 이 글은 실무에서 자주 마주치는 선택지와 구현 패턴을 중심으로 정리한 설계이다.