[Spring] REST API 버저닝과 @RequestMapping

1. API 버저닝이란?

API 버저닝(API Versioning)은 API의 버전을 관리하여 기존 클라이언트와의 하위 호환성을 유지하면서 API를 발전시키는 방법이다.

API를 운영하다 보면 기존 API의 응답 형식이나 기능을 변경해야 하는 상황이 발생할 수 있다.

이때 기존 클라이언트가 갑자기 동작하지 않도록 기존 버전을 유지하면서 새로운 버전을 제공할 수 있다.

예를 들어 기존 API가 다음과 같다고 가정한다.

/api/v1/posts

이후 API의 구조가 변경되었다면 기존 API를 수정하는 대신 새로운 버전을 만들 수 있다.

/api/v2/posts

기존 클라이언트는 v1을 계속 사용하고, 새로운 클라이언트는 v2를 사용하도록 할 수 있다.

2. API 버저닝이 필요한 이유

API 버저닝을 사용하는 주요 이유는 다음과 같다.

• 하위 호환성 유지
  기존 클라이언트가 새로운 API 변경으로 영향을 받지 않도록 한다.
• 점진적인 업그레이드
  클라이언트가 준비된 시점에 새로운 API 버전으로 변경할 수 있다.
• 서비스 안정성 확보
  기존 API를 사용하는 서비스를 유지하면서 새로운 API를 제공할 수 있다.
• 다양한 클라이언트 지원
  웹, 모바일 앱, 외부 서비스 등 여러 클라이언트가 서로 다른 API 버전을 사용할 수 있다.

3. @RequestMapping으로 API 버전 관리하기

Spring에서는 @RequestMapping을 사용하여 컨트롤러의 공통 URL 경로를 지정할 수 있다.

API 버전을 URL에 포함하는 경우 @RequestMapping을 이용해 다음과 같이 작성할 수 있다.

@RestController
@RequestMapping("/api/v1/posts")
public class PostController {

    @GetMapping("/list")
    public List<PostDto> list() {
        // ...
    }
}

이 경우 실제 요청 URL은 다음과 같다.

GET /api/v1/posts/list

@RequestMapping은 공통 URL을 지정하는 역할을 하고, 여기에 버전 정보를 포함하면 API 버전을 URL 기준으로 관리할 수 있다.

4. 타임리프에서는 API 버저닝이 상대적으로 필요하지 않은 이유

타임리프는 서버 사이드 렌더링(SSR) 방식으로 동작한다.

서버에서 HTML을 완성해서 브라우저에 전달하기 때문에 REST API처럼 별도의 클라이언트가 API 응답 형식에 직접 의존하는 구조가 아니다.

반면 REST API는 프론트엔드, 모바일 앱, 외부 서비스 등 다양한 클라이언트가 서버의 API를 사용할 수 있다.

따라서 API의 응답 형식이나 구조가 변경되면 기존 클라이언트에 영향을 줄 수 있고, 이를 방지하기 위해 API 버저닝이 필요하다.

SSR과 REST API의 차이

구분	타임리프(SSR)	REST API
화면 생성	서버에서 HTML 생성	클라이언트가 화면 생성
서버 역할	데이터 + HTML 제공	데이터 제공
주요 클라이언트	웹 브라우저	웹, 모바일, 외부 서비스 등
API 버전 관리	상대적으로 필요성이 낮음	변경 시 필요할 수 있음

즉, 타임리프에서는 서버와 화면이 함께 관리되는 반면, REST API에서는 서버와 클라이언트가 분리되어 있기 때문에 버전 관리의 필요성이 커진다.