9.1 KiB
title, source_type, url, archive_url, status, confidence, tags, related_branches, related_projects, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_branches | related_projects | created | last_reviewed | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Stripe API versioning — date-based rolling versions | company-tech-blog | https://stripe.com/blog/api-versioning | raw | high |
|
|
|
2026-05-22 | 2026-05-27 |
Stripe API versioning — date-based rolling versions
Layer:
raw/company-tech-blogs/— Stripe 엔지니어링 블로그의 versioning 정책 원문 발췌. ca-tmpl 이 채택한90d public + 30d internal migration window + Sunset header결정의 대안 (removal 없이 freeze) 평가용.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-api-compatibility-deprecation-contract | API versioning 대안 평가 — date-based "freeze forever" (대안 1) 비교. version change module 패턴이 ca-tmpl 의 compatibility adapter 와 유사한지 검토 |
| raw/project-notes/ca-skeleton-operational-contract | API evolution & schema contract 의 외부 벤더 사례. freeze 모델 vs migration window 모델의 정책 차이 명문화 |
컨텍스트 / 왜 저장했는지
ca-tmpl 은 "deprecate → 90일 public / 30일 internal migration window → 제거" 를 default 로 두지만, Stripe 는 field/endpoint 를 영구히 제거하지 않고 version pinning 으로 freeze 하는 정반대 전략을 씀. 두 전략의 trade-off 를 비교하기 위해 보관.
출처 / Source
- 원본 URL: https://stripe.com/blog/api-versioning
- 아카이브 URL: (미수집)
- 저자 / 조직: Stripe Engineering (Brandur Leach 등)
- 발행일: 2017-08 (원문 게시), 이후 docs 로 이관
- 마지막 확인일: 2026-05-27
핵심 인용 / Key quotes (verbatim)
[§Version naming] "rolling versions that are named with the date they're released (for example,
2017-05-24)"
[§Account pinning] "The first time a user makes an API request, their account is automatically pinned to the most recent version available"
[§Field stability] "Fields that were present before should stay present, and fields should always preserve their same type and name."
[§API stability — analogy] "Like a connected power grid or water supply, after hooking it up, an API should run without interruption for as long as possible."
[§Override] "Users can override the version of any single request by manually setting the
Stripe-Versionheader, or upgrade their account's pinned version from Stripe's dashboard."
[§Version change modules] "Version change modules keep older API versions abstracted out of core code paths. Developers can largely avoid thinking about them while they're building new products."
[§Breaking changes — incremental] "Although backwards-incompatible, each one contains a small set of changes that make incremental upgrades relatively easy"
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| STRIPE-APIV-C1 | API 버전 식별자는 release 날짜 기반 (예: 2017-05-24) |
[§Version naming] "rolling versions that are named with the date they're released (for example, 2017-05-24)" |
company-case-study |
Stripe API versioning 정책 | date-based 가 semver 보다 일반적으로 우월하다는 뜻은 아님 — vendor 선택 |
| STRIPE-APIV-C2 | 사용자가 첫 API 요청 시 계정이 자동으로 가장 최신 버전에 pin 됨 (이후 명시 변경 전까지 유지) | [§Account pinning] "The first time a user makes an API request, their account is automatically pinned to the most recent version available" | company-case-study |
Stripe 의 계정 단위 version pinning | 모든 SaaS 가 account-level pinning 을 채택해야 한다는 일반화 금지 |
| STRIPE-APIV-C3 | field 는 한 번 노출되면 이름·타입 보존, 제거하지 않음 (backward compatibility 정책) | [§Field stability] "Fields that were present before should stay present, and fields should always preserve their same type and name." | company-case-study |
Stripe API 의 field lifecycle | 모든 vendor 가 field 를 영구 보존해야 한다는 뜻은 아님 — Stripe 의 정책적 약속 |
| STRIPE-APIV-C4 | Stripe 는 web API 안정성을 연결된 power grid / water supply 에 비유 — 한번 연결되면 가능한 한 오래 중단 없이 운영되어야 함 | [§API stability — analogy] "Like a connected power grid or water supply, after hooking it up, an API should run without interruption for as long as possible." | company-case-study |
Stripe 의 API stability 철학 | 인용된 analogy 는 마케팅·철학 선언이지 기술적 명제 아님 — best practice 로 격상 금지 |
| STRIPE-APIV-C5 | 사용자는 Stripe-Version 헤더로 단일 요청 단위 override 가능, 또는 대시보드에서 self-directed 로 pinned version 업그레이드 가능 |
[§Override] "Users can override the version of any single request by manually setting the Stripe-Version header, or upgrade their account's pinned version from Stripe's dashboard." |
company-case-study |
Stripe API 의 version override 메커니즘 | 헤더 + 대시보드 외 다른 채널 (API call, SDK config) 의 존재 여부는 본 인용 범위 밖 |
| STRIPE-APIV-C6 | Stripe 는 version change modules 로 옛 버전을 core code 와 격리, 신규 개발 시 옛 버전을 의식하지 않게 함 | [§Version change modules] "Version change modules keep older API versions abstracted out of core code paths. Developers can largely avoid thinking about them while they're building new products." | company-case-study |
Stripe 내부 코드 구조 | version change module 구현 세부 (어디서 분기, 어떻게 테스트) 는 본 인용에 없음 |
| STRIPE-APIV-C7 | breaking change 는 작은 단위로 분산되어 dated release 에 묶임 — 점진적 upgrade 를 쉽게 하기 위함 | [§Breaking changes — incremental] "Although backwards-incompatible, each one contains a small set of changes that make incremental upgrades relatively easy" | company-case-study |
Stripe 의 breaking change release 방식 | 작은 dated release 가 모든 API 에 적합하다는 뜻은 아님 — Stripe 의 throughput/리뷰 부담을 감당할 수 있어야 함 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
STRIPE-APIV-C1~C2: date-based version 명명 + account 자동 pinningSTRIPE-APIV-C3: field 영구 보존 정책 (이름·타입)STRIPE-APIV-C5~C6: 헤더 override + dashboard upgrade + version change module 격리STRIPE-APIV-C7: breaking change 의 작은 dated release 분산
- 이 자료가 증명하지 않는 것:
- Stripe 가 endpoint 전체 (path operation) 를 영구히 제거하지 않는다는 명시 — 인용은 field 보존만 직접 언급
- account pinning 의 expiry / 강제 마이그레이션 정책 (현 시점에 EOL 이 없다는 뜻인지)
- version change module 의 성능 비용 / 테스트 부담 정량 데이터
- Stripe 모델이 모든 SaaS 의 best practice 라는 명제 —
company-case-study강도, 격상 금지
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 이 internal-first 일 때 Stripe 모델 전면 도입은 과함 (외부 SDK consumer 가 거의 없음)
- ca-tmpl 의 compatibility adapter (legacy enum → 새 enum 매핑) 가 Stripe 의 version change module 아이디어와 유사한지 검증 (코드 비교 필요)
메모 / Notes
검증되지 않은 내 해석은 wiki source-summary 단계에서 작성.
- 버전 식별자: 날짜 (
2017-05-24형태). 의미적 major bump 없음. - breaking change 처리: 작은 dated release 로 분산. major version jump 회피.
- ca-tmpl 결정과의 차이 (해석):
- ca-tmpl: deprecate marker + 90d window + 강제 removal. catalog 7행으로 분류.
- Stripe: 절대 removal 안 함. 모든 클라이언트는 자기가 pin 한 버전을 영원히 받음. version change 모듈이 core 에서 분기.
- Trade-off (해석, 미검증):
- Stripe 방식 장점: 외부 SDK·integrator 가 깨질 일이 거의 없음. PR 리뷰에서 breaking 여부 판정이 단순 (전부 새 dated version).
- Stripe 방식 단점: version change 모듈을 매번 작성·테스트해야 함. legacy 버전 유지비가 누적. 내부 도메인 모델까지 다중 표현을 안고 가야 함.
- ca-tmpl 방식 장점: 운영 부담 한정 (특히 internal-only API). breaking diff 를 CI 에서 깰 수 있음.
- ca-tmpl 방식 단점: 외부 컨슈머가 많을수록 migration window 합의 비용이 큼.
Related / 관련
- 같은 주제 다른 raw:
- raw/company-tech-blogs/api-versioning-github-rest-date-header (대안 3: GitHub header + 24개월 EOL + 410 Gone)
- 인용하는 branch:
- 인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract (Group G-F — API evolution & schema)
- 인용한 wiki 요약: (미작성)