llm-wiki/vault/20-evidence/official-docs/google-aip-233-batch-create.md

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	tags	status	confidence	created	last_reviewed
official-doc / Google AIP-233 — Batch Methods: Create	official-doc	https://google.aip.dev/233		Google	feature-api-contract-baseline	ca-skeleton	official-doc ca-skeleton api-contract google-aip bulk-operation	raw	high	2026-05-31	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 결정