112 lines
9.0 KiB
Markdown
112 lines
9.0 KiB
Markdown
---
|
|
title: GitHub REST API versioning — X-GitHub-Api-Version header
|
|
source_type: company-tech-blog
|
|
url: https://docs.github.com/en/rest/overview/api-versions
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-tmpl, api-versioning, deprecation, github, header-versioning]
|
|
related_branches: [feature-api-compatibility-deprecation-contract]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# GitHub REST API versioning — `X-GitHub-Api-Version` header
|
|
|
|
> Layer: `raw/company-tech-blogs/` — GitHub 공식 REST API docs 원문 발췌. Stripe 와 같은 date-based versioning 이지만 **URL 이 아닌 헤더**로 전달하고 24개월 EOL 후 `410 Gone` 강제 종료를 채택한 변형.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] | API versioning 대안 평가 — header-based date versioning (대안 3) + 24개월 EOL + `410 Gone` 응답 코드의 catalog 도입 근거 |
|
|
| [[raw/project-notes/ca-skeleton-operational-contract]] | API evolution & schema contract 의 외부 벤더 사례. EOL 응답 코드 catalog (RFC 8594 Sunset 후 `410 Gone`) 의 vendor 근거 |
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
ca-tmpl 이 검토한 대안 중 **GitHub REST API headers** 의 실제 운영 모델. Stripe 의 "freeze forever" 와 ca-tmpl 의 "90d window" 의 **중간 지점** (24개월 명시 EOL + `410 Gone` 강제 종료).
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.github.com/en/rest/overview/api-versions
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: GitHub (REST API docs)
|
|
- 발행일: 2022-11-28 첫 도입, 이후 dated releases (rolling)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§API versioning] "You should use the `X-GitHub-Api-Version` header to specify an API version."
|
|
|
|
> [§Default version] "Requests without the `X-GitHub-Api-Version` header will default to use the `2022-11-28` version."
|
|
|
|
> [§Version naming] "The API version name is based on the date when the API version was released."
|
|
|
|
> [§Breaking changes] "Breaking changes are changes that can potentially break an integration."
|
|
|
|
> [§Breaking changes — announcement] "Breaking changes will be released in a new API version. We will provide advance notice before releasing breaking changes."
|
|
|
|
> [§Closing down API version] "If you specify an API version that is no longer supported, you will receive a `410 Gone` response."
|
|
|
|
> [§Support window] "When a new REST API version is released, the previous API version will be supported for at least 24 more months."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| GH-APIV-C1 | API version 선택은 `X-GitHub-Api-Version` 요청 헤더로 지정한다 (URL path 가 아님) | [§API versioning] "You should use the `X-GitHub-Api-Version` header to specify an API version." | `official-vendor-doc` | GitHub REST API 의 모든 endpoint | URL 기반 versioning 이 더 나쁘다는 일반 명제가 아님 — GitHub 의 운영 선택일 뿐 |
|
|
| GH-APIV-C2 | 헤더 없는 요청은 default 로 `2022-11-28` 버전을 받는다 (헤더 미지정 시 명시적 default 적용) | [§Default version] "Requests without the `X-GitHub-Api-Version` header will default to use the `2022-11-28` version." | `official-vendor-doc` | GitHub REST API 요청 | "default 가 항상 최신" 이라는 뜻은 아님 — 고정된 dated default |
|
|
| GH-APIV-C3 | API 버전 이름은 **release 날짜** 기반 (예: `2022-11-28`) | [§Version naming] "The API version name is based on the date when the API version was released." | `official-vendor-doc` | GitHub REST API 버전 식별자 | semver / major bump 모델보다 우월하다는 뜻은 아님 — vendor 선택 |
|
|
| GH-APIV-C4 | Breaking change 는 **integration 을 깰 수 있는 변경**으로 정의되며, 구체적 예: operation 제거, parameter 제거/이름 변경, response field 제거/이름 변경, 새 required parameter 추가, optional → required 변경, type 변경, enum value 제거, 새 validation rule 추가, 인증/인가 요구 변경 | [§Breaking changes] "Breaking changes are changes that can potentially break an integration." + 항목 리스트: "Removing an entire operation", "Removing or renaming a parameter", "Removing or renaming a response field", "Adding a new required parameter", "Making a previously optional parameter required", "Changing the type of a parameter or response field", "Removing enum values", "Adding a new validation rule to an existing parameter", "Changing authentication or authorization requirements" | `official-vendor-doc` | GitHub 의 breaking change 정책 | 이 목록이 모든 API 의 breaking 정의에 일반적으로 적용된다는 뜻은 아님 — GitHub 의 선언 |
|
|
| GH-APIV-C5 | Breaking change 는 **새 API 버전으로 release** 되며, 사전 공지(advance notice) 가 원칙 (단, 보안/가용성 사유 시 즉시 적용 예외) | [§Breaking changes — announcement] "Breaking changes will be released in a new API version. We will provide advance notice before releasing breaking changes." | `official-vendor-doc` | GitHub REST API 의 breaking change 통보 | 사전 공지 기간 (며칠/주/개월) 의 구체적 SLA 는 본 인용에 없음 |
|
|
| GH-APIV-C6 | 지원 종료된 API version 요청은 **`410 Gone`** 응답을 받는다 | [§Closing down API version] "If you specify an API version that is no longer supported, you will receive a `410 Gone` response." | `official-vendor-doc` | EOL 된 GitHub REST API version 요청 | EOL 전 별도 Sunset / Deprecation 헤더의 발행 여부는 본 인용 범위 밖 |
|
|
| GH-APIV-C7 | 새 REST API version release 시 직전 version 은 **최소 24개월** 추가 지원 (지원 윈도우 명시) | [§Support window] "When a new REST API version is released, the previous API version will be supported for at least 24 more months." | `official-vendor-doc` | GitHub REST API 의 버전 lifecycle | 24개월 이 모든 API vendor 의 표준이라는 뜻은 아님. Stripe 무제한 / ca-tmpl 90일 등 vendor 별 다름 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `GH-APIV-C1` ~ `C3`: GitHub 의 header-based date versioning 메커니즘 (헤더 이름, default 버전, 명명 규칙)
|
|
- `GH-APIV-C4` ~ `C5`: breaking change 정의 + 사전 공지 원칙
|
|
- `GH-APIV-C6` ~ `C7`: EOL 시 `410 Gone` + 24개월 지원 윈도우
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- header-based versioning 이 URL-based versioning 보다 일반적으로 우수하다는 명제
|
|
- 24개월 윈도우가 모든 enterprise API 의 표준이라는 일반화
|
|
- Sunset / Deprecation HTTP 헤더 (RFC 8594 / draft-deprecation-header) 와의 결합 방식 (본 페이지에는 명시 없음)
|
|
- 사전 공지의 정확한 lead time (days/weeks/months)
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-tmpl 이 internal-first 일 때 24개월 윈도우가 과한지 (현 결정: 90d public / 30d internal)
|
|
- `410 Gone` 응답을 ca-tmpl error code catalog 에 추가 시 client-side handling 패턴 (재시도 금지 vs 명시 마이그레이션 안내)
|
|
- GitHub 처럼 release notes + deprecation header 채널을 verification suite 로 강제할 수 있는지
|
|
|
|
## 메모 / Notes
|
|
|
|
> 검증되지 않은 내 해석은 wiki source-summary 단계에서 작성.
|
|
|
|
- Stripe vs GitHub vs ca-tmpl 비교:
|
|
|
|
| | Stripe | GitHub | ca-tmpl |
|
|
| --- | --- | --- | --- |
|
|
| 버전 식별 | `Stripe-Version` header + account pin | `X-GitHub-Api-Version` header | URL `/v1` + OpenAPI deprecated marker |
|
|
| EOL 정책 | 없음 (freeze forever) | next release 후 24개월 | 90d public / 30d internal |
|
|
| EOL 시 응답 | 영원히 정상 | `410 Gone` | (ca-tmpl 결정 안 됨) |
|
|
| breaking 단위 | dated release | dated release | per field/operation |
|
|
|
|
- ca-tmpl 보강 포인트 (해석, 미검증):
|
|
- **EOL 응답 코드** 가 catalog 에 빠져 있음. RFC 8594 Sunset 시점 후 `410 Gone` 을 default 응답 코드로 catalog 에 추가 후보.
|
|
- GitHub 처럼 advance notice 채널 (release notes, deprecation header) 을 verification suite 에서 강제할 수 있음.
|
|
- Trade-off (해석, 미검증):
|
|
- GitHub 모델 장점: URL 안정성. routing/cache 단순. version 은 헤더로만 분기.
|
|
- GitHub 모델 단점: URL 만 보고 어느 버전인지 모름 → 로그/메트릭에서 `X-GitHub-Api-Version` 을 항상 같이 기록해야 함.
|
|
- ca-tmpl 이 URL versioning 유지 시 internal-first 라 routing 단순. 외부 공개 시 GitHub 모델 검토 가치.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 raw:
|
|
- [[raw/company-tech-blogs/api-versioning-stripe-date-based]] (대안 1: Stripe freeze forever)
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] (대안 3)
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] (Group G-F — API evolution & schema)
|
|
- 인용한 wiki 요약: (미작성)
|