130 lines
14 KiB
Markdown
130 lines
14 KiB
Markdown
---
|
|
title: "official-doc / Google AIP-233 — Batch Methods: Create"
|
|
source_type: official-doc
|
|
url: https://google.aip.dev/233
|
|
archive_url:
|
|
vendor: Google
|
|
related_branches: [feature-api-contract-baseline]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, api-contract, google-aip, bulk-operation]
|
|
status: raw
|
|
confidence: high
|
|
created: 2026-05-31
|
|
last_reviewed: 2026-05-31
|
|
---
|
|
|
|
# official-doc / Google AIP-233 — Batch Methods: Create
|
|
|
|
> Layer: `raw/official-docs/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
|
|
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-api-contract-baseline]] | D23 (bulk operation URL pattern): `POST /v1/{resource}:batchCreate` colon-verb syntax — `:batchCreate` verb 명칭 자체의 normative 근거. 기존 AIP-136 은 colon-verb *패턴* 만 정의하지만 AIP-233 은 `:batchCreate` *명칭 vocabulary* 를 직접 normative 하게 정의하여 D23 의 `UNSUPPORTED_IMPL_DECISION` 라벨 해소 |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://google.aip.dev/233
|
|
- 아카이브 URL: (미확인)
|
|
- 저자 / 조직: Google (AIP editors)
|
|
- 발행일: (Google AIP 페이지, 정확한 최초 발행일 비노출)
|
|
- 마지막 확인일: 2026-05-31
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`feature-api-contract-baseline` D23 의 bulk operation URL pattern 결정에서 `:batchCreate` verb 명칭의 출처가 AIP-136 (colon-verb 패턴 일반 원칙) 까지만 corroborate 되어 `UNSUPPORTED_IMPL_DECISION` 라벨이 잔존하고 있었다. AIP-233 이 `:batchCreate` 명칭을 URI pattern 으로 직접 normative 하게 정의하므로, 본 raw 보관이 D23 의 `:batchCreate` 명칭 vocabulary 근거를 완성한다.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Core Definition] "Some APIs need to allow users to create multiple resources in a single transaction. A batch create method provides this functionality."
|
|
|
|
> [§HTTP Requirements / Verb] "The HTTP verb **must** be `POST`."
|
|
|
|
> [§HTTP Requirements / URI Pattern] "The HTTP URI **must** end with `:batchCreate`."
|
|
|
|
> [§Request Structure] "The request message **must** include a repeated field which accepts the request messages specifying the resources to create...The field **should** be named `requests`."
|
|
|
|
> [§Parent Field Consistency] "If a caller sets this field, and the `parent` field of any child request message does not match, the request **must** fail."
|
|
|
|
> [§Response Structure] "The response message **must** include one repeated field corresponding to the resources that were created."
|
|
|
|
> [§Atomicity Constraint] "Synchronous batch create **must** be atomic."
|
|
|
|
> [§Atomicity Constraint] "Asynchronous batch create **may** support atomic or partial success."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| AIP233-C1 | Batch Create 는 단일 트랜잭션에서 여러 리소스를 생성하는 메서드다 | [§Core Definition] "Some APIs need to allow users to create multiple resources in a single transaction. A batch create method provides this functionality." | `official-reference` | Google AIP 를 따르는 API 설계 | 어떤 트랜잭션 구현 방식(DB 트랜잭션 / saga / 2PC)을 사용해야 하는지는 정의하지 않는다 |
|
|
| AIP233-C2 | Batch Create 의 HTTP verb 는 MUST `POST` 다 | [§HTTP Requirements / Verb] "The HTTP verb **must** be `POST`." | `official-reference` | Google AIP 준수 API — batch create endpoint | PUT/PATCH/DELETE 를 사용하는 다른 batch 유형은 별도 AIP (AIP-234 등) 에서 정의됨 |
|
|
| AIP233-C3 | Batch Create URI 는 MUST `:batchCreate` 로 끝나야 한다 | [§HTTP Requirements / URI Pattern] "The HTTP URI **must** end with `:batchCreate`." | `official-reference` | Google AIP 준수 API 의 batch create endpoint URI | URI 의 나머지 구조 (`{parent}/` prefix 등) 는 리소스 설계에 따라 달라짐. IETF/W3C 표준이 아닌 Google AIP community guideline |
|
|
| AIP233-C4 | Request message 는 MUST repeated field 를 포함해야 하며, SHOULD `requests` 로 명명한다 | [§Request Structure] "The request message **must** include a repeated field which accepts the request messages specifying the resources to create...The field **should** be named `requests`." | `official-reference` | Google AIP 준수 API 의 batch create request message | `requests` 이외의 명칭 사용은 SHOULD 위반이지만 MUST 위반이 아니다. REST JSON body 에서 field 이름으로 직접 매핑됨 (protobuf 컨텍스트 — REST 매핑은 추가 설계 필요) |
|
|
| AIP233-C5 | `parent` field 가 설정된 경우, child request 의 `parent` field 가 다르면 request 는 MUST 실패해야 한다 | [§Parent Field Consistency] "If a caller sets this field, and the `parent` field of any child request message does not match, the request **must** fail." | `official-reference` | Google AIP 준수 API 의 batch create — parent scoped resource 에 한해 적용 | parent field 가 없는 batch create (top-level resource) 에는 적용되지 않는다. 실패 응답 형태 (HTTP status code / error body shape) 는 본 AIP 가 직접 정의하지 않는다 |
|
|
| AIP233-C6 | Response message 는 MUST 생성된 리소스를 담은 하나의 repeated field 를 포함해야 한다 | [§Response Structure] "The response message **must** include one repeated field corresponding to the resources that were created." | `official-reference` | Google AIP 준수 API 의 batch create response message | repeated field 의 명칭 (예: `books`) 은 리소스 유형에 따라 달라지며 AIP-233 이 직접 정의하지 않는다 |
|
|
| AIP233-C7 | 동기 Batch Create 는 MUST atomic (all-or-nothing) 이어야 한다 | [§Atomicity Constraint] "Synchronous batch create **must** be atomic." | `official-reference` | Google AIP 준수 API 의 **동기** batch create | 비동기 batch create 에는 적용되지 않는다. atomicity 의 구현 방법 (DB 단일 트랜잭션, distributed transaction 등) 은 정의하지 않는다 |
|
|
| AIP233-C8 | 비동기 Batch Create 는 atomic 또는 partial success 를 MAY 지원한다 | [§Atomicity Constraint] "Asynchronous batch create **may** support atomic or partial success." | `official-reference` | Google AIP 준수 API 의 **비동기** batch create | partial success 를 지원한다고 해서 어떤 상황에서 partial 을 허용할지 기준을 정의하지 않는다. partial success metadata 구조는 별도 AIP 섹션 (Async Only) 에서 정의됨 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
### 이 자료가 직접 증명하는 것
|
|
|
|
- `AIP233-C2`: batch create endpoint 의 HTTP verb 가 MUST `POST` 임
|
|
- `AIP233-C3`: batch create URI 가 MUST `:batchCreate` suffix 로 끝나야 함 — D23 의 `:batchCreate` *verb 명칭* vocabulary 의 normative 근거
|
|
- `AIP233-C4`: request message 에 `requests` field (repeated, SHOULD 명칭) 가 MUST 포함됨
|
|
- `AIP233-C5`: parent field 불일치 시 MUST fail 의 정합성 규칙
|
|
- `AIP233-C6`: response message 에 created 리소스의 repeated field 가 MUST 포함됨
|
|
- `AIP233-C7`: 동기 batch create 의 atomicity MUST 요건
|
|
|
|
### 이 자료의 authority level 주의사항
|
|
|
|
- **AIP-233 은 Google 내부 API community guideline 이다** (`official-reference` 수준). IETF RFC / W3C 표준 / OpenAPI Initiative 표준 수준의 `official-standard` 가 아니다. Google API Design Guide 의 community-governed 문서로 타사에 대한 법적 구속력이 없다.
|
|
- 본 AIP 는 **protobuf / gRPC 컨텍스트** 에서 기술되어 있다. REST JSON API 에 적용할 때는 field 명칭이 JSON body 로 직접 매핑되지만, protobuf message 구조 (`BatchCreateXxxRequest`, `BatchCreateXxxResponse`) 자체를 채택할 의무는 없다.
|
|
|
|
### 이 자료가 증명하지 않는 것
|
|
|
|
- **`:batchCreate` 가 IETF 표준** 임을 증명하지 않는다 — Google AIP community guideline 이다
|
|
- **`feature-api-contract-baseline` D23 의 `BATCH_PARTIAL_FAILURE` envelope category** 와 AIP-233 의 atomicity/partial success 정책의 완전한 정합성: D23 은 HTTP 200 + envelope.success=false + `BATCH_PARTIAL_FAILURE` 로 부분 실패를 표현하지만, AIP-233 의 async partial success 는 `map<int32, google.rpc.Status> failed_requests` + `Operation.error` 구조를 정의한다. 본 branch 는 AIP-233 의 protobuf Operation shape 을 채택하지 않고 **자체 REST envelope** (`data.results[]` 항목별 success/error) 를 사용한다. 이 REST envelope 은 project-internal 결정이며 AIP-233 이 직접 normative 하게 정의하지 않는다.
|
|
- **`requests` field 명칭이 REST JSON body field 명** 으로 강제됨을 증명하지 않는다 — AIP-233 의 `requests` 명칭은 SHOULD (권고)이며, REST 매핑은 project 내부 결정이다
|
|
- **batch size limit** (예: 최대 1000 항목): AIP-233 은 문서화 권고만 하며 숫자를 normative 하게 정의하지 않는다
|
|
|
|
### AIP-233 atomicity 정책과 D23 `BATCH_PARTIAL_FAILURE` 의 정합성
|
|
|
|
D23 은 부분 실패를 HTTP 200 + `BATCH_PARTIAL_FAILURE` 로 처리하며, 이는 **전체 실패가 아닌 부분 성공/실패** 모델이다. AIP-233 의 관점:
|
|
|
|
- **동기 batch create** (AIP233-C7) = MUST atomic → D23 의 부분 실패 모델은 동기 endpoint 에 적용 시 AIP-233 atomicity 요건과 **충돌**한다. D23 이 부분 실패를 허용한다면 해당 endpoint 는 AIP-233 기준에서 "비동기 또는 AIP 미준수" 로 분류된다.
|
|
- **비동기 batch create** (AIP233-C8) = MAY support partial success → D23 의 부분 실패 모델은 비동기 endpoint 에서 AIP-233 과 일치한다.
|
|
- **결론**: D23 의 `BATCH_PARTIAL_FAILURE` 은 AIP-233 이 허용하는 partial success 의 *의미론* 과 부합하지만, *표현 형식* (REST envelope vs AIP-233 의 Operation metadata 구조) 은 project-internal 결정으로 남는다. D23 이 동기 endpoint 에서 partial 실패를 허용하면 AIP-233 C7 (동기 MUST atomic) 과 충돌 발생 — 이 trade-off 는 본 branch 에서 명시적 결정이 필요하다 (현재 `UNSUPPORTED_IMPL_DECISION` 잔존).
|
|
|
|
### 잔존 UNSUPPORTED_IMPL_DECISION (D23 기준 — claim-traceability gate 결과)
|
|
|
|
아래 3건은 AIP-233 이 직접 normative 하게 정의하지 않으므로 `UNSUPPORTED_IMPL_DECISION` 라벨이 잔존한다. 이 자료만으로 증명되지 않는다.
|
|
|
|
| 항목 | 왜 UNSUPPORTED_IMPL_DECISION | 해소 경로 |
|
|
|---|---|---|
|
|
| `data.results[]` REST envelope shape (항목별 success/error 구조) | AIP-233 C6 은 protobuf `repeated Book books` 만 정의. REST envelope 의 `data.results[]` + 항목별 `{success, error}` 구조는 project-internal — boundary branch B14 (BulkEnvelope.partial) SSOT | boundary branch B14 의 BulkEnvelope 스펙이 확정되면 cross-cite 로 보강 |
|
|
| 부분 실패 표현 = HTTP 200 + `envelope.success=false` 조합 | AIP-233 C8 은 async partial success 의 *허용 여부* 만 정의. 표현 형식(HTTP 200 + false envelope vs AIP 의 `Operation.error` + `failed_requests` map)은 project-internal trade-off | 동기/비동기 endpoint 구분 명확화 후 foundation envelope SSOT 와 cross-cite |
|
|
| 동기 endpoint 에서 `BATCH_PARTIAL_FAILURE` 허용 여부 | AIP233-C7 (동기 MUST atomic) 과 D23 의 partial failure 허용 이 충돌. D23 이 동기/비동기를 명확히 구분하지 않으면 AIP233-C7 위반 위험 | D23 을 (a) 동기는 all-or-nothing MUST, (b) 비동기 전용으로 partial 허용 으로 명시 분기하거나, (c) ca-skeleton 이 AIP-233 의 동기 atomicity 요건 미준수임을 명시 |
|
|
|
|
### 내 프로젝트에 적용하려면 추가 확인이 필요한 것
|
|
|
|
- D23 이 동기 vs 비동기 endpoint 를 명확히 구분하는지 확인 (AIP233-C7 충돌 해소 — 위 UNSUPPORTED_IMPL_DECISION 3번)
|
|
- `feature-operational-error-observability-foundation` 의 `BATCH_PARTIAL_FAILURE` envelope category 정의가 AIP-233 의 partial success semantics 와 의미론적으로 정합하는지 cross-branch review
|
|
- REST `requests` field 명칭 채택 여부 (D23 현재 `{ requests: [...] }` 를 body shape 로 정의 — AIP233-C4 SHOULD 와 일치하므로 추가 근거 불필요)
|
|
|
|
## 메모 / Notes
|
|
|
|
- AIP-233 은 protobuf 기반 gRPC API 를 primary target 으로 한다. REST HTTP transcoding 은 Google HTTP Transcoding (AIP-127) 에서 별도로 다룬다. 본 branch 는 REST JSON API 이므로 protobuf Message 구조 (`BatchCreateXxxRequest`) 를 직접 채택하지 않는다 — D23 의 `{ requests: [...] }` body shape 는 AIP-233 의 `requests` field SHOULD 명칭과 **일치**하므로 이 부분은 자연스럽게 정합됨.
|
|
- AIP-233 이 정의하는 partial success 의 `map<int32, google.rpc.Status> failed_requests` 구조는 본 branch 의 `data.results[]` (각 항목별 success/error) 와 **의미론적으로 동등**하지만 형식이 다르다. D23 의 REST envelope 매핑은 project-internal.
|
|
- AIP-233 C7 (동기 MUST atomic) 은 강력한 제약이다. D23 이 synchronous endpoint 에서 `BATCH_PARTIAL_FAILURE` 를 허용하면 AIP-233 준수 여부가 문제가 된다. 이 점은 ca-skeleton 설계 결정으로 명시 필요 (향후 D23 row 의 Open Risk 보강 권고).
|
|
|
|
## Related / 관련
|
|
|
|
- [[raw/official-docs/google-aip-136-custom-methods]] — AIP-136: colon-verb URI pattern 의 일반 원칙 (AIP-233 이 `:batchCreate` 를 특정 vocabulary 로 normative 정의하는 것의 상위 원칙)
|
|
- [[raw/official-docs/google-aip-151-long-running-operations]] — AIP-151: batch create 의 비동기 variant (LRO 반환) 에 대한 Operation shape 정의
|
|
- [[raw/branch-notes/feature-api-contract-baseline]] — D23 (bulk operation URL pattern): 본 raw 를 인용하는 branch 결정
|