82 lines
4.0 KiB
Markdown
82 lines
4.0 KiB
Markdown
---
|
|
title: blog-topic / api-deprecation-sunset-header-migration-window
|
|
source_type: blog-topic
|
|
status: raw
|
|
related_branches: [feature-api-compatibility-deprecation-contract]
|
|
related_projects: [ca-tmpl]
|
|
tags: [blog-topic, ca-tmpl, api-design, ietf, api-contract, version-scheme]
|
|
created: 2026-07-02
|
|
status_label: ready-for-canonical
|
|
target_audience: backend-engineer
|
|
inspiration_url:
|
|
archive_url:
|
|
---
|
|
|
|
# blog-topic: api-deprecation-sunset-header-migration-window
|
|
|
|
> Layer: `raw/blog-topics/` — 작업 중 나온 블로그 글감 원석. 최종 블로그는 canonical 정제 후 `wiki/blog/`에서 작성한다.
|
|
|
|
## Parent / 부모
|
|
|
|
- [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] — API deprecation과 compatibility contract 설계에서 나온 글감.
|
|
|
|
## 트리거 / Trigger
|
|
|
|
- 트리거 유형: `branch-work`
|
|
- 트리거 날짜: 2026-07-02
|
|
- 트리거 연결 노트: [[raw/branch-notes/feature-api-compatibility-deprecation-contract]]
|
|
|
|
## 글감 / Topic seed
|
|
|
|
- 한 문장 요지: API versioning과 deprecation을 분리하고 `Sunset`/`Deprecation` header, migration window, compatibility fixture를 어떻게 연결할지 정리한다.
|
|
- 예상 제목 후보:
|
|
- API deprecation은 versioning과 어떻게 다를까
|
|
- Sunset header를 보낸다고 deprecation 운영이 끝나는 것은 아니다
|
|
|
|
## 핵심 주장 후보 / Claim candidates
|
|
|
|
- 사실 후보:
|
|
- branch에 D5-D8로 `Sunset`/`Deprecation` header pairing, migration window, compatibility fixture가 정리되어 있다 — 근거 후보: [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] D5-D8, section+line `:143-170`.
|
|
- 경험 후보:
|
|
- 90/30 migration window와 OpenAPI `deprecated` 근거는 확인 필요 경계로 남아 있다.
|
|
- 의견/해석 후보:
|
|
- deprecation은 "버전을 하나 더 만드는 일"이 아니라 client에게 시간, 신호, migration path를 제공하는 운영 계약이다.
|
|
|
|
## Outline seed
|
|
|
|
1. versioning과 deprecation을 분리하기 — 새 버전 제공과 기존 surface 종료 예고는 다른 문제다.
|
|
2. HTTP header는 사람용 공지가 아니라 machine-readable signal이다 — `Sunset`, `Deprecation`, `Link` 관계를 나눈다.
|
|
3. migration window는 project policy다 — 외부 표준처럼 말하지 않고 ca-tmpl 결정으로 표시한다.
|
|
|
|
## Canonical 전환 후보 / Canonical extraction candidates
|
|
|
|
- `wiki/projects/ca-tmpl/api-evolution-and-schema.md` 후보:
|
|
- ca-tmpl API deprecation project decision.
|
|
- `wiki/concepts/api-evolution-and-schema.md` 후보:
|
|
- API compatibility, deprecation, sunset header 일반 개념.
|
|
- 필요한 추가 검증:
|
|
- OpenAPI `deprecated` 근거, migration window의 project-local status, header pairing source claim.
|
|
|
|
## Sources / 근거 후보
|
|
|
|
- [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] — D5-D8 deprecation decision 근거.
|
|
|
|
## 미해결 / Unknown
|
|
|
|
- 아직 확인해야 할 사실: 90/30 window와 OpenAPI deprecated marker가 source-backed인지 project convention인지.
|
|
- 과장하면 안 되는 부분: 실제 운영 deprecation 경험처럼 쓰면 안 된다. ca-tmpl은 운영 배포 검증이 없다.
|
|
- 블로그로 쓰기 전에 필요한 canonical 정제: `UNSUPPORTED_DECISION`과 source-backed decision 분리.
|
|
|
|
## Decision / 처리 결정
|
|
|
|
- 액션: `promote-to-canonical`
|
|
- 이유: `wiki/projects/ca-tmpl/api-evolution-and-schema.md` 의 compatibility/deprecation documented-only 섹션에 반영했다. 일반 개념은 기존 `wiki/concepts/api-evolution-and-schema.md` 가 `Sunset` / `Deprecation` 역할 분리와 OpenAPI marker 근거를 이미 포함한다.
|
|
- 다음 단계: source canonical이 `verified` 상태이므로 이후 `blogify` 대상으로 삼을 수 있다. 단 블로그 본문에서는 90/30 window를 project-local policy로 표기하고 운영 경험처럼 쓰지 않는다.
|
|
|
|
## Related / 관련
|
|
|
|
- 관련 branch: [[raw/branch-notes/feature-api-compatibility-deprecation-contract]]
|
|
- 관련 error:
|
|
- 관련 interview prep:
|
|
- derived blog: 생성 전. 생성 시 `wiki/blog/api-deprecation-sunset-header-migration-window-YYYY-MM-DD.md` 후보
|