🔍 API 버전 관리는 왜 필요할까?
API는 시간이 지나면서 새로운 기능이 추가되거나 기존 기능이 변경될 수 있습니다.
하지만 기존 API를 그대로 변경하면 기존 클라이언트가 예상치 못한 오류를 겪을 수 있기 때문에, API 버전 관리를 통해 안정적으로 서비스를 운영해야 합니다.
🚀 API 버전 관리를 통해 얻을 수 있는 장점:
- 클라이언트가 원하는 버전을 선택할 수 있음
- 기존 API를 유지하면서 새로운 기능을 추가할 수 있음
- API의 변경을 점진적으로 적용 가능
📌 API 버전 관리 방법 4가지
1. URL 경로 기반 버전 관리
📢 방식:
버전을 URL 경로에 포함하여 API를 구분하는 방식 (/api/v1/, /api/v2/)
@RestController
@RequestMapping("/api")
public class UrlController {
@GetMapping("v1/url")
public String getUrlV1() {
return "url v1";
}
@GetMapping("v2/url")
public String getUrlV2() {
return "url v2";
}
}
📌 장점:
✅ 직관적이고 이해하기 쉬움
✅ API Gateway 및 캐싱 적용이 쉬움
✅ RESTful 설계 원칙과 잘 맞음
❌ 단점:
⚠️ URL이 길어질 수 있음
⚠️ 오래된 버전을 유지하면 API가 많아질 수 있음
🎥 동작확인
2. 요청 파라미터 기반 버전 관리 (?version=1)
📢 방식:
API 요청 시 ?version=1 또는 ?version=2와 같은 쿼리 파라미터를 사용
@RestController
@RequestMapping("/api/param")
public class ParamController {
@GetMapping(params = "version=1")
public String getParamV1() {
return "param v1";
}
@GetMapping(params = "version=2")
public String getParamV2() {
return "param v2";
}
}
📌 장점:
✅ URL이 동일하므로 깔끔함
✅ 클라이언트가 쉽게 버전을 선택할 수 있음
❌ 단점:
⚠️ API Gateway에서 캐싱 적용이 어려움
⚠️ 검색 엔진(SEO)에 불리함
🎥 동작확인
3. 헤더 기반 버전 관리 (X-API-VERSION)
📢 방식:
HTTP 요청 헤더를 이용하여 버전을 관리
@RestController
@RequestMapping("/api/header")
public class HeaderController {
@GetMapping(headers = "X-API-VERSION=1")
public String getHeaderV1() {
return "header v1";
}
@GetMapping(headers = "X-API-VERSION=2")
public String getHeaderV2() {
return "header v2";
}
}
📌 장점:
✅ URL이 변경되지 않아 깔끔함
✅ 클라이언트가 API 버전을 쉽게 변경할 수 있음
❌ 단점:
⚠️ 브라우저에서 직접 호출이 어려움
⚠️ API 문서화가 필수적
🎥 동작확인
4. 미디어 타입 기반 버전 관리 (Accept 헤더 사용)
📢 방식:
클라이언트가 Accept 헤더에 버전을 포함하여 요청
@RestController
@RequestMapping("/api/accept")
public class AcceptController {
@GetMapping(produces = "application/vnd.company.app-v1+json")
public String getAcceptV1() {
return "accept v1";
}
@GetMapping(produces = "application/vnd.company.app-v2+json")
public String getAcceptV2() {
return "accept v2";
}
}
📌 장점:
✅ RESTful 원칙을 따름
✅ API 응답 포맷을 쉽게 확장 가능
❌ 단점:
⚠️ API Gateway에서 미디어 타입 기반 라우팅이 필요함
⚠️ 클라이언트에서 별도의 설정이 필요함
🎥 동작확인
📊 실제로 많이 쓰는 API 버전 관리 방식은?
버전 관리 방식실무 활용도주요 사용 사례
| URL 경로 기반 | ⭐⭐⭐⭐⭐ | RESTful API, 외부 공개 API |
| 요청 파라미터 기반 | ⭐⭐⭐ | 일부 클라이언트 선택 가능 API |
| 헤더 기반 | ⭐⭐⭐⭐ | 내부 API, 보안이 중요한 API |
| 미디어 타입 기반 | ⭐⭐ | RESTful 원칙을 엄격하게 따를 때 |
✅ 결론:
실무에서는 URL 경로 기반 (/api/v1/) 방식이 가장 많이 사용됩니다.
내부 API에서는 헤더 기반 (X-API-VERSION) 방식도 고려할 수 있습니다.
🚀 마무리
API 버전 관리는 서비스 확장성을 위해 필수적인 요소입니다.
📌 실무에서 권장하는 API 버전 관리 방식:
✔ URL 기반 → 외부 API에 가장 적합
✔ 헤더 기반 → 내부 API 관리에 유리