[아키텍처] API 버전 정책 실적용 (/api/v1 또는 헤더)

[RosieOh]

🧑‍💻 오늘의 개발하면서 생긴 크고 작은 이슈사항을 기록해주세요

💚 어떤 기능인가요?

[ API ] API 버전 정책(/api/v1 또는 헤더)을 실제 서비스 라우팅에 적용합니다.
Breaking change 시 클라이언트 호환성을 유지할 수 있도록 버전 전략을 명확히 합니다.

✅ To Dos

• 경로 버전 vs 헤더 버전 전략 결정
• 컨트롤러/라우팅 공통 규칙 반영
• 기존 엔드포인트 호환 정책(redirect/deprecate) 수립
• OpenAPI 문서 버전 표기 반영
• README/클라이언트 가이드 업데이트
• 버전 미지정 요청 처리 정책 테스트

[RosieOh]

남겨 둡니다. 제가 단독으로 정할 수 없는 결정입니다.

현재 상태를 정리하면, BaseController 에 @RequestMapping("/api/v1") 이 선언돼 있지만 실제로는 적용되지 않습니다. 컨트롤러들이 각자 @RequestMapping("/policies") 처럼 자기 경로를 선언하면서 덮어쓰기 때문입니다. 즉 /api/v1 은 죽은 선언입니다.

이걸 실제로 적용하면 모든 클라이언트 경로가 바뀝니다. 모바일 앱은 배포된 버전이 남아 있어서, 서버만 바꾸면 구버전 앱이 전부 404 를 받습니다.

그래서 결정에 앞서 확인이 필요합니다.

• 현재 배포된 클라이언트가 있는가, 강제 업데이트가 가능한가
• 경로 방식(/api/v1/...)과 헤더 방식(Accept-Version) 중 무엇을 택할 것인가
• 전환 기간 동안 구·신 경로를 병행할 것인가

참고로 지금 경로 체계는 접근제어 매트릭스에 전수 정리돼 있어, 어떤 경로가 영향을 받는지는 바로 확인할 수 있습니다.