llm-wiki/raw/official-docs/google-aip-136-custom-methods.md

---
title: "official-doc / Google AIP-136 — Custom Methods"
source_type: official-doc
url: https://google.aip.dev/136
archive_url:
vendor: Google
related_branches: [feature-api-contract-baseline]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, api-design, google-aip, custom-method]
status: raw
confidence: high
created: 2026-05-31
last_reviewed: 2026-05-31
---

# 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)

## Related / 관련

- [[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 요약: (생성 시 링크)