Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

12 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, vendor, related_branches, related_projects, tags, status, confidence, created, last_reviewed

title

source_type

url

archive_url

vendor

related_branches

related_projects

official-doc / Google AIP-122 — Resource Names

Layer: raw/official-docs/ — Google API Improvement Proposals(AIP) 공식 문서 원문 발췌. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch (필수)

이 자료는 혼자 존재하지 않는다. 어느 branch의 구현 결정의 근거로서 보관됨.

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-api-contract-baseline	(future B13 — 현재 branch 미결) Resource URL naming convention (plural lowercase collection segment). sample-ticket fixture 의 `/v1/tickets` 같은 collection name 명명 기준 — AIP-122 의 collection identifier 규칙이 직접 근거 후보.

출처 / Source

원본 URL: https://google.aip.dev/122
아카이브 URL: (미등록)
저자 / 조직: Google LLC (AIP editors)
발행일: (AIP — 지속 업데이트, 확인일 기준)
마지막 확인일: 2026-05-31

왜 저장했는지 / Why archived

feature-api-contract-baseline 의 §5.2 Next-Session Raw Boost Plan 에서 명시된 신설 예정 raw 자료 중 하나. resource URL naming convention (collection segment 의 plural, lowercase 규칙) 의 외부 근거로 Google AIP-122 가 1차 reference 후보로 지목됨. 본 branch 의 /v1/tickets URL 패턴 결정의 normative 근거를 제공할 수 있는지 검토 목적으로 보관.

핵심 인용 / Key quotes (verbatim, 5문장)

[§ Resource names — intro] "Most APIs expose resources (their primary nouns) which users are able to create, retrieve, and manipulate. Additionally, resources are named: each resource has a unique identifier that users use to reference that resource, and these names are what users should store as the canonical names for the resources."

[§ Collection identifiers — plural] "The collection identifier segments in a resource name must be the plural form of the noun used for the resource."

[§ Collection identifiers — format] "Collection identifiers must begin with a lower-cased letter and contain only ASCII letters and numbers (/[a-z][a-zA-Z0-9]*/)."

[§ Resource ID segments — user-specified] "If resource IDs are user-specified, the API must document allowed formats. User-specified resource IDs should conform to RFC-1034...Additionally, user-specified resource IDs should restrict letters to lower-case (^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$)."

[§ Resource name components — hierarchy] "Resource name components should usually alternate between collection identifiers (example: publishers, books, users) and resource IDs (example: 123, les-miserables, vhugo1802)."

[§ Full vs relative resource names] "Note: Resource names as described here are used within the scope of a single API (or else in situations where the owning API is clear from the context), and are only required to be unique within that scope. For this reason, they are sometimes called relative resource names to distinguish them from full resource names"

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
AIP122-C1	Resource name 은 URI path schema 를 따르는 계층적 식별자이며, 각 resource 는 고유 name 을 가지고 사용자는 이 name 을 canonical 식별자로 저장해야 한다	[§ intro] "each resource has a unique identifier that users use to reference that resource, and these names are what users should store as the canonical names for the resources."	`official-reference`	Google API 설계 — protobuf/gRPC 컨텍스트 기본, HTTP REST 매핑은 AIP-127 별도 참조	REST URL path 가 곧 AIP resource name 과 동일하다는 것. HTTP REST URL 의 normative 기준이 AIP-122 단독이라는 것
AIP122-C2	Collection identifier segment 는 반드시 resource 유형의 복수형 명사여야 한다	[§ Collection identifiers] "The collection identifier segments in a resource name must be the plural form of the noun used for the resource."	`official-reference`	Google AIP 를 따르는 API 설계. REST API URL collection segment 의 plural 규칙 근거로 cross-cite 가능	모든 REST API 표준이 반드시 plural 을 사용해야 한다는 것 (AIP 는 Google 사내 community guideline 이며 IETF/W3C 표준 아님)
AIP122-C3	Collection identifier 는 소문자로 시작해야 하며 ASCII 문자와 숫자만 포함한다 (`/[a-z][a-zA-Z0-9]*/`)	[§ Collection identifiers] "Collection identifiers must begin with a lower-cased letter and contain only ASCII letters and numbers (`/[a-z][a-zA-Z0-9]*/`)."	`official-reference`	Google AIP collection identifier 의 문자 집합 규칙	kebab-case (하이픈 포함) collection identifier 가 허용된다는 것 — regex 에 하이픈 없음. 본 AIP 는 lowerCamelCase 형태를 허용하나 REST path segment 에서 실제로 camelCase 를 쓰는지 여부는 AIP-127 참조 필요
AIP122-C4	Resource ID segment 는 user-specified 인 경우 RFC-1034 준수를 권고하며 소문자 제한 regex `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$` 를 권고	[§ Resource IDs] "User-specified resource IDs should conform to [RFC-1034]...user-specified resource IDs should restrict letters to lower-case (`^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`)."	`official-reference`	user-specified resource ID (slug/handle 형태). SHOULD 이므로 강제 아님	system-generated ID (UUID 등) 에 적용된다는 것 — 본 문서는 server-assigned ID 포맷을 normative 하게 제한하지 않음
AIP122-C5	Resource name 은 collection identifier 와 resource ID 가 번갈아 나타나는 계층 구조이며, 단일 API 범위 내에서 사용되는 것은 relative resource name, API service name 을 포함하면 full resource name 이다	[§ Hierarchy] "Resource name components should usually alternate between collection identifiers...and resource IDs"; [§ Full/Relative] "they are sometimes called relative resource names to distinguish them from full resource names"	`official-reference`	Google API 의 resource name 구조 전반 — parent/child resource 관계 표현 방식	REST URL 의 versioning (`/v1`) 이 AIP resource name 구조 안에 포함된다는 것. AIP 의 full resource name 은 REST URL 과 다른 개념 (schemeless URI — `//service/path`, REST 는 `https://service/v1/path`)

Strength 허용값 참고

본 문서의 모든 Claim 은 official-reference 로 분류.
AIP 는 Google 사내 API community guideline 이며 IETF RFC / W3C 표준이 아니다.
official-vendor-doc 가 아닌 official-reference 로 분류한 이유: AIP 는 특정 Google 제품 (Cloud, Kubernetes 등) 의 공식 API 문서가 아니라 Google 내부 API 설계 guideline 의 공개 버전.

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것

AIP122-C2: REST API 의 collection segment 를 복수형으로 명명해야 하는 근거 — Google AIP 기준. /v1/tickets, /v1/publishers 같은 패턴의 tickets, publishers 가 plural 이어야 함을 support.
AIP122-C3: collection segment 가 소문자로 시작하고 ASCII 문자·숫자만 써야 한다는 것.
AIP122-C4: user-specified resource ID 의 권고 포맷 (소문자 + 숫자 + 하이픈, 최대 63자).
AIP122-C5: resource name 의 collection/ID 교대 계층 구조 패턴.

이 자료가 증명하지 않는 것

AIP 는 IETF/W3C 표준이 아니다. official-reference strength — Google API community guideline. 이 근거만으로 REST API 표준이라고 주장할 수 없다.
AIP-122 는 주로 protobuf/gRPC 컨텍스트다. REST URL path 로의 매핑은 별도 AIP-127 (HTTP and gRPC Transcoding) 가 다룬다. /v1/tickets 같은 REST URL 패턴이 AIP-122 단독으로 normative 하게 결정된다는 것은 본 인용 범위 밖.
collection identifier regex (/[a-z][a-zA-Z0-9]*/) 에는 하이픈이 없다. kebab-case collection segment (/v1/ticket-comments) 는 AIP-122 의 collection identifier 규칙에 직접 합치하지 않음 — AIP-122 는 lowerCamelCase (ticketComments) 형태를 허용. kebab-case 허용 여부는 AIP-127 또는 별도 REST guideline 참조 필요.
/v1 versioning prefix 가 AIP resource name 구조 안에 있다는 것. AIP 의 full resource name 은 //service/path (schemeless URI, 버전 미포함) 이며 REST URL https://service/v1/path 와 다른 개념. versioning 근거는 AIP-185 (별도 raw 기 보관).
sample-ticket fixture 의 /v1/tickets/{id} 결정의 normative 근거가 AIP-122 단독이라는 것. AIP-122 는 collection name plural + lowercase 를 corroborate 하지만 URL 전체 구조의 normative 기준으로 단독 사용은 부족 — AIP-127 cross-cite 필요.

내 프로젝트에 적용하려면 추가 확인이 필요한 것

AIP-127 (HTTP and gRPC Transcoding) 정독 필요: REST URL path 와 AIP resource name 의 매핑 규칙. kebab-case collection segment 허용 여부 확인.
REST API collection segment 의 공식 표준 여부: AIP-122 는 Google 기준. IETF 차원의 REST 리소스 명명 표준은 RFC 3986 (URI) 이나 별도 naming convention 표준 없음 — de facto 관행만 존재. AIP-122 를 cross-cite 할 때 "Google API guideline 기반" 임을 명시할 것.
sample-ticket fixture 의 resource ID 포맷: AIP122-C4 (user-specified ID — RFC-1034 준수 권고) 가 ticket fixture 의 ID 결정에 적용되는지 — 현재 resource ID format SSOT 는 feature-api-contract-baseline 의 out-of-scope (미결, §Cross-branch Contract Map 참조).
/v1/tickets 의 직접 normative 근거 교차 확인: AIP-122 (collection plural, lowercase) + AIP-185 (URI /v1 versioning) 를 양쪽 cross-cite 해야 URL 패턴 전체의 근거가 완성됨.

메모 / Notes

AIP-122 의 collection identifier 는 lowerCamelCase 를 표준으로 한다 (userEvents, ticketComments). REST path 에서의 kebab-case vs camelCase 선택은 AIP-127 에서 다루는 내용으로 추정 — 다음 세션에 AIP-127 raw 신설 권고.
AIP 는 Google Cloud API Design Guide 의 전신 / 발전 형태. 별도 "Google Cloud API Design Guide" 도 관련 자료이나 AIP 가 더 세부 규칙을 담음.
AIP122-C3 의 regex [a-z][a-zA-Z0-9]* 는 camelCase 를 허용한다 (대문자 포함). 본 프로젝트가 kebab-case path segment 를 선택했다면 AIP-122 의 collection identifier 규칙을 직접 따르는 것이 아닌 "정신적으로 일치" 수준임을 명시할 것.
AIP-122 는 resource alias (users/me 같은 semantic alias) 도 허용하되 "all data returned from the API must use the canonical resource name" 원칙을 명시 — alias endpoint 설계 시 참조 가능.

AIP-127 (HTTP and gRPC Transcoding): REST URL path ↔ AIP resource name 매핑 — 반드시 cross-cite. raw/official-docs/google-aip-127-http-transcoding (미신설 — 다음 세션 신설 권고)
AIP-185 (Resource Versioning): URI /v1 prefix 규칙 — 기 보관. raw/official-docs/google-aip-185-resource-versioning
AIP-180 (Backwards Compatibility): backward compatibility 의무 cross-cite. raw/official-docs/api-versioning-google-aip-180
AIP-132 (List method): sort parameter syntax — 미신설. raw/official-docs/google-aip-132-list-method (§5.2 신설 예정)
AIP-151 (Long-Running Operations): LRO 응답 패턴 — 미신설. raw/official-docs/google-aip-151-long-running-operations (§5.2 신설 예정)
RFC 3986 (URI Syntax): URI 전반 문법 정의 — 별도 cross-cite 필요 시
이 자료를 인용한 wiki 요약: wiki/concepts/rest-resource-naming (생성 전)

12 KiB Raw Permalink Blame History