REST API 구현에서 API 버저닝을 하는 이유
이번 글에서는 REST API 구현 시 왜 API 버저닝이 필요한지를 정리한다.
특히 Thymeleaf 방식과 REST API 방식의 차이,
그리고 프론트엔드 개발자와의 협업 관점에서
API 버저닝이 왜 중요한 개념인지 다룬다.
1️⃣ REST API는 “협업”을 전제로 한다
REST API의 가장 큰 특징 중 하나는
프론트엔드 개발자와의 협업을 전제로 한다는 점이다.
✔ REST API 방식
- 백엔드: 데이터(JSON) 제공
- 프론트엔드(React, Vue 등): API 호출 후 화면 렌더링
👉 즉, API는 프론트엔드가 직접 사용하는 계약(Contract) 이 된다.
2️⃣ 타임리프 방식에서는 왜 버저닝이 필요 없을까?
타임리프 / JSP 방식의 특징
- UI(View)가 스프링부트 내부에 존재
- 서버가 HTML을 완성해서 내려줌
- 클라이언트(브라우저)는 API를 직접 호출하지 않음
즉,
- 서버 코드 변경
- HTML 구조 변경
- 데이터 구조 변경
👉 전부 서버에서 한 번에 수정되며
👉 다음 요청부터 즉시 반영된다.
결론
타임리프 방식은 사실상 단일 클라이언트(웹 브라우저) 이고,
서버 개발자가 모든 것을 관리하므로
API 버저닝이 굳이 필요하지 않다.
3️⃣ REST API에서 버저닝이 중요한 이유
REST API는 상황이 완전히 다르다.
- 프론트엔드 개발자가 따로 있음
- 모바일 앱, 웹 앱 등 여러 클라이언트가 동시에 API를 사용
- 이미 배포된 클라이언트가 존재
이 상태에서 API 응답 구조를 갑자기 바꾸면?
👉 기존 프론트가 깨짐
👉 앱 업데이트 전까지 오류 발생
👉 서비스 안정성 하락
4️⃣ API 버저닝이란?
✔ 정의
API 버저닝(API Versioning) 이란
API의 버전을 관리하여 하위 호환성을 유지하면서 API를 발전시키는 방법이다.
✔ 목적
- 기존 클라이언트가 정상 동작하도록 유지
- 새로운 기능/개선 사항을 안전하게 추가
- 프론트엔드가 점진적으로 마이그레이션 가능
✔ 버저닝 방식
- URL 경로 방식 (가장 흔함)
- HTTP Header 방식
- Query Parameter 방식
이 강의에서는 URL 경로 방식을 사용한다.
5️⃣ URL 기반 API 버저닝 예시
v1 API
GET /api/v1/posts
응답 필드: createDatev2 API (필드명 변경)
GET /api/v2/posts
createDate → createdDatev3 API (리소스 명까지 변경)
GET /api/v3/articles
createdDate👉 기존 /api/v1/posts를 사용하는 프론트는 아무 영향도 받지 않는다
👉 새로운 프론트는 /api/v2, /api/v3를 선택적으로 사용 가능
6️⃣ API 버저닝을 하는 이유 정리
✅ 1. 하위 호환성 유지
- 기존 클라이언트가 깨지지 않음
- 이미 배포된 앱/웹 안정성 보장
✅ 2. 점진적 업그레이드
- 프론트엔드가 새로운 버전으로 천천히 이동 가능
- 한 번에 전면 수정할 필요 없음
✅ 3. 안정성
- 프로덕션 환경에서 API 변경 시
- 서비스 중단 없이 개선 가능
✅ 4. 다양한 클라이언트 지원
- 웹
- 모바일 앱
- 외부 서비스(서드파티)
👉 각 클라이언트가 자신에게 맞는 API 버전을 사용 가능
7️⃣ 그럼 언제 버저닝이 굳이 필요 없을까?
✔ 이런 경우라면 필수는 아님
- 혼자 React + Spring Boot를 모두 개발
- 프론트/백엔드가 동시에 수정 가능
- 외부 클라이언트가 없음
이 경우에는 REST API를 사용하더라도
버저닝이 필수는 아니다.
8️⃣ 하지만 “협업”을 생각하면?
REST API는 결국 사람과 사람 사이의 약속이다.
- 프론트 개발자와 협업
- 시간이 지나도 깨지지 않는 API
- 안정적인 서비스 운영
👉 이런 관점에서 API 버저닝은 매우 좋은 선택이다.
🔚 6강 정리
- REST API는 프론트엔드와의 협업을 전제로 한다
- API 변경은 곧 프론트엔드 장애로 이어질 수 있다
- API 버저닝을 통해 하위 호환성을 유지할 수 있다
- 타임리프 방식은 서버 내부에서 모든 것이 처리되므로 버저닝 필요성이 낮다
- 협업과 확장을 고려한다면 API 버저닝은 필수적인 설계 요소다
💡 한 줄 요약
API 버저닝은 기술적인 문제가 아니라,
협업과 서비스 안정성을 위한 선택이다.
