8.9 KiB
title, source_type, url, archive_url, status, confidence, related_branches, related_projects, tags, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | related_branches | related_projects | tags | created | last_reviewed | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Google AIP-185 — Versioning (resource major version + channel stability) | official-doc | https://google.aip.dev/185 | raw | high |
|
|
|
2026-05-27 | 2026-05-27 |
Google AIP-185 — Versioning (resource major version + channel stability)
Layer:
raw/official-docs/— Google API Improvement Proposals 의 API versioning 정책. ca-tmpl API contract baseline 의 major version 결정 (D2) 과 deprecation contract (D6) 의 reference. AIP 는 Google internal API design guideline 이지만 외부에 reference 로 널리 인용됨 (정식 IETF/W3C 표준 아님).
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-api-contract-baseline | D2 (major version 을 URL path 에 노출 — /v1/...) + D6 (alpha/beta/stable 채널 분리 또는 stable-only) 결정의 reference |
| raw/branch-notes/feature-api-compatibility-deprecation-contract | major version bump 의 조건 / 기존 major 와 새 major 의 의존성 금지 정책 reference |
컨텍스트 / 왜 저장했는지
ca-tmpl API contract baseline 에서 "왜 URL path 에 major version 만 노출하는가 (/v1/, 절대 /v1.0/ 아님)", "왜 alpha/beta 를 별도 채널로 분리하는가" 결정의 1차 reference. AIP-180 (backwards compatibility) 과 짝을 이루는 문서 — AIP-180 은 같은 major 안에서의 호환, AIP-185 는 major bump 자체의 규칙.
출처 / Source
- 원본 URL: https://google.aip.dev/185
- 관련 AIP: AIP-180 (Backwards compatibility), AIP-181 (Stability levels)
- 아카이브 URL: (미수집)
- 저자 / 조직: Google (API Improvement Proposals working group)
- 발행일: continuously updated
- 마지막 확인일: 2026-05-27 (WebFetch verbatim 확인)
핵심 인용 / Key quotes (verbatim, captured 2026-05-27)
[§Guidance] "All Google API interfaces must provide a major version number, which is encoded at the end of the protobuf package"
[§Guidance] "Google APIs must not expose minor or patch version numbers. For example, Google APIs use
v1, notv1.0"
[§Guidance] "A new major version of an API must not depend on a previous major version of the same API"
[§Channel-based versioning] "The alpha and beta channel must have their stability level appended to the version, but the stable channel must not"
[§Channel-based versioning] "The beta channel's functionality must be a superset of the stable channel's functionality"
[§Deprecating API functionality] "Deprecated API functionality must not graduate from alpha to beta, nor beta to stable"
[§Release-based versioning] "Both the channel-based and release-based strategies update the stable version in-place"
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| AIP185-C1 | 모든 Google API interface 는 major version number 를 노출해야 함 (protobuf package 끝에 인코딩) | [§Guidance] "All Google API interfaces must provide a major version number, which is encoded at the end of the protobuf package" | official-reference (Google AIP — community guideline, 표준 아님) |
URL path versioning 결정 (/v1/...) |
REST API 에서 path vs header 중 어느 위치인지는 본 인용 범위 밖 — AIP 는 protobuf 컨텍스트 |
| AIP185-C2 | Google API 는 minor 또는 patch version 을 노출하면 안 됨 (v1.0 아닌 v1) |
[§Guidance] "Google APIs must not expose minor or patch version numbers. For example, Google APIs use v1, not v1.0" |
official-reference |
path 에 /v1.0/ 같은 minor 표기 금지 결정 |
semver 자체를 부정하는 것은 아님 — public surface 노출만 금지, internal release semver 는 별도 |
| AIP185-C3 | 새 major version 은 같은 API 의 이전 major version 에 의존하면 안 됨 | [§Guidance] "A new major version of an API must not depend on a previous major version of the same API" | official-reference |
v2 가 v1 코드를 import 하는 구조 금지 | shared common types (예: google.protobuf.Timestamp) 의 공유는 별도 — 본 인용은 같은 API 의 다른 major 간 의존만 |
| AIP185-C4 | alpha / beta 채널은 stability level 을 version 에 append 해야 하지만 stable 채널은 append 하면 안 됨 | [§Channel-based versioning] "The alpha and beta channel must have their stability level appended to the version, but the stable channel must not" | official-reference |
v1beta1, v1alpha1 vs v1 명명 규칙 |
채널 별 SLA / 호환성 보장 수준은 본 인용 범위 밖 — AIP-181 영역 |
| AIP185-C5 | beta 채널 기능은 stable 채널 기능의 superset 이어야 함 | [§Channel-based versioning] "The beta channel's functionality must be a superset of the stable channel's functionality" | official-reference |
beta 가 stable 보다 적은 기능을 노출하는 것 금지 | alpha 가 beta 의 superset 인지는 본 인용 범위 밖 (AIP 다른 섹션 또는 AIP-181 위임) |
| AIP185-C6 | Deprecated API 기능은 alpha → beta 또는 beta → stable 로 graduate 되면 안 됨 | [§Deprecating API functionality] "Deprecated API functionality must not graduate from alpha to beta, nor beta to stable" | official-reference |
deprecation 후 채널 승격 금지 정책 | deprecation 통지 window / sunset 일정은 본 인용 범위 밖 — AIP-180 / AIP-214 위임 |
| AIP185-C7 | channel-based / release-based 두 versioning 전략 모두 stable version 을 in-place 로 업데이트 | [§Release-based versioning] "Both the channel-based and release-based strategies update the stable version in-place" | official-reference |
stable v1 이 시간에 따라 (호환 범위 내) 진화한다는 가정 | stable 안에서 어떤 변경이 호환인지는 본 인용 범위 밖 — AIP-180 위임 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것 (2026-05-27 WebFetch verbatim 확인):
AIP185-C1: major version 노출 의무 (protobuf 컨텍스트)AIP185-C2: minor / patch 노출 금지 —/v1/만,/v1.0/금지AIP185-C3: 새 major 가 이전 major 에 의존 금지AIP185-C4: alpha/beta 는 stability level append, stable 은 append 금지AIP185-C5: beta = stable 의 supersetAIP185-C6: deprecated 기능은 채널 승격 금지AIP185-C7: stable 은 in-place 업데이트
- 이 자료가 증명하지 않는 것:
- REST URL path 에서 major version 의 정확한 위치 — AIP 는 protobuf 컨텍스트, REST 매핑은 별도 (AIP-122 / Cloud Endpoints 위임)
- major version bump 의 trigger (어떤 변경이 major bump 를 요구하는지) — AIP-180 위임
- deprecation 통지 window / sunset 일정 — AIP-214 위임
- channel 별 SLA / 가용성 보장 — AIP-181 (Stability levels) 위임
- Google AIP 는 internal guideline 이며 IETF/W3C 표준 아님. 외부 인용 시 "Google API style guide" 로 명시.
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 이 REST 기반 — AIP-185 의 "protobuf package" 규칙을 URL path 로 매핑하는 근거 (AIP-122 또는 별도 reference 확인)
- ca-tmpl 이 alpha/beta 채널을 실제로 운영할지 여부 — internal-first skeleton 에서는 stable-only 도 합리적 trade-off
v1beta1같은 명명을 채택할 경우 Spring Boot URL routing 패턴 호환성
메모 / Notes
- AIP-180 과의 관계: AIP-180 은 같은 major 안에서의 backwards compatibility, AIP-185 는 major bump 자체의 규칙. 두 문서는 짝.
- REST vs gRPC: AIP 자체는 protobuf/gRPC 중심. REST 매핑은 별도 AIP (AIP-122 등) 또는 Google Cloud Endpoints 문서.
- Stripe 모델과의 차이: Stripe 는 date-based versioning (
Stripe-Version: 2024-04-10). AIP-185 는 major-only path versioning. 두 모델 중 ca-tmpl 이 어느 쪽을 택할지는 별도 결정. - internal-first skeleton 함의: alpha/beta 채널 분리는 운영 부담이 큼. ca-tmpl 이 stable-only 로 시작하고 필요시 beta 채널 추가하는 것이 합리적 trade-off.
Related / 관련
- 같은 주제 다른 official-doc:
- raw/official-docs/api-versioning-google-aip-180 (같은 major 안에서의 호환)
- AIP-181 (Stability levels) — 별도 raw 작성 후보
- 인용하는 branch:
- 인용하는 project:
- 인용한 wiki 요약: (미작성)