donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
main
llm-wiki/raw/company-tech-blogs/api-versioning-github-rest-date-header.md
T

9.0 KiB
Raw Permalink Blame History

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
GitHub REST API versioning — X-GitHub-Api-Version header company-tech-blog https://docs.github.com/en/rest/overview/api-versions raw high
ca-tmpl
api-versioning
deprecation
github
header-versioning
feature-api-compatibility-deprecation-contract
ca-skeleton-operational-contract
2026-05-22 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

핵심 인용 / 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 / 관련

Reference in New Issue View Git Blame Copy Permalink