106 lines
8.9 KiB
Markdown
106 lines
8.9 KiB
Markdown
---
|
|
title: Google AIP-185 — Versioning (resource major version + channel stability)
|
|
source_type: official-doc
|
|
url: https://google.aip.dev/185
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
related_branches: [feature-api-contract-baseline, feature-api-compatibility-deprecation-contract]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
tags: [ca-tmpl, api-versioning, aip-185, google, major-version, stability-channel, official-doc]
|
|
created: 2026-05-27
|
|
last_reviewed: 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`, not `v1.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 의 superset
|
|
- `AIP185-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:
|
|
- [[raw/branch-notes/feature-api-contract-baseline]]
|
|
- [[raw/branch-notes/feature-api-compatibility-deprecation-contract]]
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]]
|
|
- 인용한 wiki 요약: (미작성)
|