107 lines
9.1 KiB
Markdown
107 lines
9.1 KiB
Markdown
---
|
|
title: Stripe API versioning — date-based rolling versions
|
|
source_type: company-tech-blog
|
|
url: https://stripe.com/blog/api-versioning
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-tmpl, api-versioning, deprecation, stripe, date-based, backward-compat]
|
|
related_branches: [feature-api-compatibility-deprecation-contract]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 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-Version` header, 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 자동 pinning
|
|
- `STRIPE-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:
|
|
- [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] (대안 1)
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] (Group G-F — API evolution & schema)
|
|
- 인용한 wiki 요약: (미작성)
|