배경
Stripe는 수백만 개발자가 사용하는 결제 API를 제공합니다. API를 지속적으로 개선하면서도 기존 통합을 깨뜨리지 않아야 합니다. 10년 이상 하위호환성을 유지하면서 API를 진화시켜왔습니다.
도전 과제
수백만 기존 통합의 하위호환성을 유지하면서 API를 개선해야 합니다. Breaking change를 도입할 때 기존 사용자에게 영향을 주지 않으면서 새 사용자에게는 최신 API를 제공해야 합니다. 버전 관리의 복잡성이 코드베이스 전체에 확산되는 것을 방지해야 합니다.
해결 방안
날짜 기반 API 버전 시스템(예: 2023-10-16)을 도입했습니다. 각 API 호출은 사용자 계정에 고정된 버전으로 처리되며, 내부적으로는 버전 변환 레이어(Version Compatibility Layer)가 요청/응답을 변환합니다. 이를 통해 내부 코드는 항상 최신 버전으로 작성하고, 변환 레이어가 구버전 호환을 담당합니다.
결과
10년 이상 하위호환성 유지, 수백만 개발자의 통합 보호, API 진화 속도 유지.
핵심 인사이트
- 1.날짜 기반 버저닝이 시맨틱 버저닝보다 API 진화에 유리
- 2.Version Compatibility Layer로 변환 로직 중앙화
- 3.API 설계는 한번 공개되면 영구적 계약
- 4.멱등성(Idempotency)은 결제 API의 핵심 안전장치