Files

T

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

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

11 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-136 — Custom Methods

Layer: raw/official-docs/ — 외부 공식 자료 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-api-contract-baseline	(future B18 — 미결) Bulk operation URL pattern — `/v1/tickets:batchCreate` Google AIP-136 colon-verb syntax 근거 (collection-based custom method 패턴). D17 LRO cross-ref: custom method (`:cancel`, `:batchCreate`) 가 LRO entry point 가 될 수 있음.

출처 / Source

원본 URL: https://google.aip.dev/136
아카이브 URL: (미등록 — 추후 archive.org 스냅샷 추가 권장)
저자 / 조직: Google (AIP Editors)
발행일: 2019-01-25 (approved)
마지막 확인일: 2026-05-31
Changelog: 2025-05-12 (preposition rationale 확장), 2025-01-09, 2023-11-16, 2023-05-16, 2023-05-09, 2023-03-02

왜 저장했는지 / Why archived

feature-api-contract-baseline 의 미결 B18 (bulk operation URL pattern) 를 정당화하기 위해 수집. Google AIP-136 은 standard CRUD 로 표현 불가능한 동작에 colon-separated verb suffix (:batchCreate, :cancel 등) 를 사용하는 custom method URI 패턴을 정의하며, collection-scoped custom method 가 batch operation 의 natural fit 임을 보여준다. D17 (LRO) 와의 cross-ref 근거로도 활용 — custom method 가 202 LRO entry point 가 될 수 있음.

중요 scope note: AIP-136 자체는 :batchCreate, :cancel 같은 구체적 verb 이름을 직접 정의하지 않는다. 그 verb 들은 AIP-231 (Batch methods), AIP-232 (Batch Get), AIP-233 (Batch Create), AIP-234 (Batch Update), AIP-235 (Batch Delete) 에 정의되어 있다. AIP-136 은 custom method 의 URI syntax 와 적용 원칙 을 정의한다. Idempotency 에 대한 normative 진술도 AIP-136 본문에는 없다.

핵심 인용 / Key quotes (verbatim)

[§Guidance 1단락] "Resource-oriented design (AIP-121) uses custom methods to provide a means to express arbitrary actions that are difficult to model using only the standard methods. Custom methods are important because they provide a means for an API's vocabulary to adhere to user intent."

[§Guidance — HTTP URI bullet] "The HTTP URI must use a : character followed by the custom verb (:archive in the above example), and the verb in the URI must match the verb in the name of the RPC."

[§Guidance — HTTP method bullets] "GET must be used for methods retrieving data or resource state." / "POST must be used if the method has side effects or mutates resources or data."

[§Resource-based custom methods] "Custom methods must operate on a resource if the API can be modeled as such"

[§Collection-based custom methods] "While most custom methods operate on a single resource, some custom methods may operate on a collection instead"

[Self-Grep verification log — /tmp/source-fetch-20260531091148.txt]

Quote 1 (express arbitrary actions): line 698 — PASS
Quote 2 (use a \:\ character followed by the custom verb`): line 738 — PASS
Quote 3 (GET **must** be used for methods retrieving): line 733 — PASS
Quote 3b (POST **must** be used if the method has side effects): line 734 — PASS
Quote 4 (Custom methods **must** operate on a resource): line 758 — PASS
Quote 5 (some custom methods **may** operate on a collection instead): line 773 — PASS

검증: V=5 P=5 D=0 C=0

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리. AIP-136 본문에 없는 내용 (batch verb 명칭, idempotency) 은 claim 으로 추출하지 않는다.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
AIP136-C1	Custom method 는 standard CRUD 로 표현하기 어려운 임의 동작을 표현하는 수단으로 resource-oriented design 에 정의된 개념이다	[§Guidance 1단락] "uses custom methods to provide a means to express arbitrary actions that are difficult to model using only the standard methods"	`official-reference`	Google AIP 를 채택한 모든 API 설계	custom method 가 모든 REST API 에서 best practice 라는 뜻이 아님 — Google API community guideline 내 컨벤션
AIP136-C2	Custom method 의 HTTP URI 는 반드시 `:` 문자 뒤에 custom verb 를 붙여야 하며, URI 의 verb 는 RPC 이름의 verb 와 반드시 일치해야 한다	[§Guidance — HTTP URI bullet] "The HTTP URI must use a `:` character followed by the custom verb [...] and the verb in the URI must match the verb in the name of the RPC"	`official-reference`	Google AIP 를 따르는 REST/gRPC-transcoded API	RFC 3986 URL 표준이 `:verb` suffix 를 특별히 정의하지 않는다는 점 — 이는 AIP 내부 컨벤션
AIP136-C3	Custom method 에서 HTTP `POST` 는 side effect 나 resource/data 변경이 있을 때 반드시 사용해야 하고, `GET` 은 데이터·상태 조회에만 반드시 사용해야 한다	[§Guidance — HTTP method bullets] "`GET` must be used for methods retrieving data or resource state." / "`POST` must be used if the method has side effects or mutates resources or data."	`official-reference`	Google AIP custom method HTTP method 선택	HTTP method 선택이 자동으로 idempotency 를 보장한다는 뜻이 아님 — AIP-136 본문에 idempotency 진술 없음
AIP136-C4	Custom method 는 API 가 resource 단위로 모델링 가능하면 반드시 resource 에 적용해야 하며, resource 이름 파라미터는 반드시 `name` 이라 칭하고 URI path 의 유일한 변수여야 한다	[§Resource-based custom methods] "Custom methods must operate on a resource if the API can be modeled as such" + "The parameter for the resource's name must be called `name`, and be the only variable in the URI path."	`official-reference`	Resource-based custom method 설계	특정 동사 어휘 (`:cancel`, `:batchCreate` 등) 의 normative 정의 — 이는 AIP-231/232/233/234/235 범위
AIP136-C5	Collection-based custom method 는 단일 resource 대신 collection 전체에 적용할 수 있으며, collection 의 부모 resource 파라미터는 반드시 `parent` 라 칭하고 collection key 는 리터럴이어야 한다	[§Collection-based custom methods] "some custom methods may operate on a collection instead" + "If the collection's resource has a parent, that resource must be called `parent` and be the only variable in the URI path." + "The collection key [...] must be literal."	`official-reference`	Collection-scoped custom method (예: batchCreate, sort 등)	batch method 의 응답 형식 (partial success 처리, 오류 envelope) — AIP-136 본문에 없음. 이는 AIP-231~235 + project-internal envelope 매핑 범위

Strength 근거

AIP (API Improvement Proposal) 는 Google 내부 community guideline 로 IETF/W3C 표준이 아님. official-reference 로 분류 (CLAUDE.md §5 참조). company-case-study 보다 강하나 official-standard (RFC/W3C) 보다 약함.

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것

AIP136-C2: /v1/{resource}:verb 형식의 colon-separated verb suffix URI syntax 가 Google AIP 에서 normative 하게 정의된 컨벤션임
AIP136-C3: Custom method 에서 mutation 은 POST, 조회는 GET 이라는 HTTP method 선택 원칙
AIP136-C4: Resource-scoped custom method 의 파라미터 명명 (name) 과 URI 변수 단일 강제
AIP136-C5: Collection-scoped custom method 의 파라미터 명명 (parent) 과 collection key 리터럴 강제

이 자료가 증명하지 않는 것

:batchCreate, :cancel, :undelete, :batchGet, :batchUpdate, :batchDelete 같은 표준 batch verb 의 normative 명칭 — 이는 AIP-231~235 에 있음. AIP-136 은 verb 형식만 정의하고 구체적 어휘는 정의하지 않는다.
Custom method 의 idempotency 분류 — AIP-136 본문에 idempotency 관련 normative 진술 없음
Colon syntax (:batchCreate) 가 RFC 3986 URL 표준 자체에서 정의된다는 것 — RFC 3986 은 : 를 path segment delimiter 로 정의하지 않음. 이는 AIP 내부 컨벤션이며 REST 클라이언트/라이브러리가 자동 지원하지 않을 수 있다.
본 branch 의 envelope BATCH_PARTIAL_FAILURE category 와 AIP-136 의 batch method 응답 형식이 동일하다는 것 — AIP-136 은 batch 응답 형식을 정의하지 않는다. project-internal 매핑 필요.
AIP 가 IETF/W3C 표준과 동등한 normative 권위를 가진다는 것 — Google API community guideline (official-reference) 임

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

:batchCreate verb 명칭의 normative 근거: AIP-233 raw 신설 필요 (raw/official-docs/google-aip-233-batch-create.md)
Batch method 의 partial failure 응답 형식: AIP-231 (Batch methods) + project-internal BATCH_PARTIAL_FAILURE envelope 매핑
:cancel verb 가 LRO entry point 로 사용되는 패턴: AIP-151 (Long-Running Operations) raw 신설 필요 (raw/official-docs/google-aip-151-long-running-operations.md)
Spring REST 환경에서 :verb suffix path 가 제대로 routing 되는지: Spring MVC PathPattern 설정 검증 필요

메모 / Notes

AIP-136 은 colon syntax 의 HTTP 라우팅 관련 주의사항을 본문에서 직접 논하지 않는다. gRPC-to-HTTP transcoding (AIP-127) 컨텍스트가 전제된 문서이므로, 순수 REST 환경에서의 적용은 additional tooling/config 필요.
Batch verb 목록 (:batchCreate, :cancel, :undelete) 은 사용자 요청에서 "AIP-136 표준 verb" 로 언급되었으나, AIP-136 본문에는 존재하지 않는다. 이는 AIP-231~235 의 내용이다. 다음 세션 raw 신설 권고: google-aip-231-batch-methods-official, google-aip-233-batch-create-official.
AIP-136 의 idempotency 관련 진술 부재: GET 이 side-effect 없음을 명시하므로 GET custom method 는 안전(safe)하다고 추론 가능하나, idempotency 자체에 대한 normative 진술은 없다. 이를 claim 으로 추출하지 않는다.
추가 봐야 할 동일 출처 페이지: AIP-231 (https://google.aip.dev/231), AIP-233 (https://google.aip.dev/233), AIP-151 (https://google.aip.dev/151), AIP-127 (https://google.aip.dev/127)

raw/branch-notes/feature-api-contract-baseline — 본 자료의 parent, D17 (LRO) + B18 (bulk operation URL pattern)
raw/official-docs/google-aip-185-resource-versioning — 동일 AIP 계열 (D2, D6 근거)
raw/official-docs/api-versioning-google-aip-180 — 동일 AIP 계열 (D6 cross-cite)
(신설 권고) raw/official-docs/google-aip-151-long-running-operations — D17 (LRO) 정당화 + :cancel verb 명칭
(신설 권고) raw/official-docs/google-aip-231-batch-methods — B18 (bulk operation) 정당화 + :batchCreate verb 명칭
이 자료를 인용한 wiki 요약: (생성 시 링크)

11 KiB Raw Permalink Blame History