토픽 116 / 192·소프트웨어 표준과 법제도

API Versioning (API 버전 관리)

API의 호환성을 유지하면서 변경·개선을 가능하게 하는 버전 관리 전략으로, URL 경로, 쿼리 파라미터, 헤더 등을 통해 버전을 지정하며 클라이언트와 서버 간 계약 관리와 점진적 마이그레이션을 지원

목적: 하위 호환성 유지, 점진적 변경, 클라이언트 마이그레이션 지원, API 진화

특징: 버전 식별, 복수 버전 지원, 단계적 폐기(Deprecation), 호환성 관리

버전 관리 전략

•URL Path Versioning: /api/v1/users, /api/v2/users, 가장 명시적, 캐싱 용이
•Query Parameter: /api/users?version=1, URL 깔끔, 선택적 버전
•Header Versioning: X-API-Version: 1, Accept: application/vnd.api.v1+json, URL 깔끔, 캐싱 어려움
•Media Type (Content Negotiation): Accept: application/vnd.company.v1+json, RESTful, 복잡

Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

Breaking Change: 필드 제거/타입 변경, 필수 파라미터 추가, 응답 구조 변경 → 새 MAJOR 버전 필요

Non-Breaking Change: 선택적 필드 추가, 새 엔드포인트 추가 → MINOR 버전 증가

Deprecation 전략: 새 버전 출시 → Deprecated 표시 → Sunset Header로 폐기 일정 공지 → 마이그레이션 기간(3~12개월) → 구 버전 폐기

장점: 하위 호환성, 점진적 마이그레이션, 명확한 계약, API 진화 가능

단점: 복수 버전 유지 부담, 코드 중복, 버전 증가, 복잡도

적용사례: 공개 API(GitHub, Stripe), 마이크로서비스, 모바일 앱 백엔드

기술요소: URL Path, Header, SemVer, Deprecation, Sunset Header

비교: URL Path(명시적/캐싱) vs Header(URL 깔끔/캐싱 어려움) vs Query(선택적)

연관: REST API, OpenAPI, 하위 호환성, Deprecation, SemVer