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-132 — Standard Methods: List

Layer: raw/official-docs/ — 외부 공식 문서의 원문 발췌·출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정

raw/branch-notes/feature-api-contract-baseline (future B14 — 현재 branch 미결) Sort parameter syntax 결정 — D7 의 sort request param 정확한 syntax (?sort=name,desc vs ?sort=-name vs ?sort=name:desc) 에 대해 AIP-132 의 order_by string 형식 ("foo desc, bar") 이 normative reference 로 기능. pagination field naming 차이 cross-cite (AIP-132: page_size/page_token snake_case proto field vs branch D7: page/size REST query string)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-api-contract-baseline	(future B14 — 현재 branch 미결) Sort parameter syntax 결정 — D7 의 `sort` request param 정확한 syntax (`?sort=name,desc` vs `?sort=-name` vs `?sort=name:desc`) 에 대해 AIP-132 의 `order_by` string 형식 (`"foo desc, bar"`) 이 normative reference 로 기능. pagination field naming 차이 cross-cite (AIP-132: `page_size`/`page_token` snake_case proto field vs branch D7: `page`/`size` REST query string)

출처 / Source

원본 URL: https://google.aip.dev/132
아카이브 URL: (미등록)
저자 / 조직: Google (API Improvement Proposals)
발행일: 2019-01-21
마지막 확인일: 2026-05-31
AIP State: Approved
마지막 갱신: 2025-02-25 (ordering well-known types clarification)

왜 저장했는지 / Why archived

AIP-132 는 Google 의 resource-oriented API 설계 지침 중 List 표준 method 의 request/response signature, pagination field 명명 (page_size, page_token, next_page_token), order_by 필드의 syntax ("foo desc, bar" 형식), filter 필드의 AIP-160 연계를 normatively 정의한다. branch feature-api-contract-baseline 의 D7 (page/size/sort request param 결정) 및 미결 B14 (sort syntax) 에 대한 official-reference 근거로 보관.

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

인용 1 — List method 표준 signature [§Guidance, line 715–716]

"The request and response messages must match the RPC name, with Request and Response suffixes."

인용 2 — Pagination fields [§Request message, line 767–768]

"The page_size and page_token fields, which support pagination, must be specified on all list request messages. For more information, see AIP-158."

인용 3 — next_page_token response field [§Response message, line 809–812]

"The next_page_token field, which supports pagination, must be included on all list response messages. It must be set if there are subsequent pages, and must not be set if the response represents the final page. For more information, see AIP-158."

인용 4 — order_by syntax (descending) [§Ordering, line 828–829]

"The default sorting order is ascending. To specify descending order for a field, users append a \" desc\" suffix; for example: \"foo desc, bar\"."

인용 5 — filter field + AIP-160 reference [§Filtering, line 850–852]

"List methods may allow clients to specify filters; if they do, the request message should contain a string filter field. Filtering is described in more detail in AIP-160."

인용 6 — HTTP verb (safe method) [§Guidance, line 717]

"The HTTP verb must be GET."

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리한다. 프로젝트 적용 결론은 ## 메모 또는 branch-note 에서만 작성.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
AIP132-C1	List method 의 RPC 는 `List` prefix 를 가지며, request/response message 는 RPC 이름과 동일한 `Request`/`Response` suffix 를 must 가진다	[§Guidance] "The request and response messages must match the RPC name, with `Request` and `Response` suffixes."	`official-reference`	Google AIP 를 따르는 API (proto-based RPC + HTTP transcoding)	REST-only API 의 URL 또는 JSON body field 명명. 본 branch 의 REST endpoint 명명 자체는 AIP-127 (HTTP/gRPC transcoding) 별도 적용 범위
AIP132-C2	List request message 는 `page_size` (int32) 와 `page_token` (string) 필드를 must 포함해야 한다	[§Request message] "The `page_size` and `page_token` fields, which support pagination, must be specified on all list request messages."	`official-reference`	Google AIP 를 따르는 proto List method	REST query string 의 파라미터 명 직접 적용 불가 — proto field 명이 REST query string 으로 변환되는 매핑은 AIP-127 §6 (HTTP transcoding) 적용. 본 branch 의 `page`/`size` query param 은 이 claim 의 직접 산출이 아님
AIP132-C3	List response message 는 `next_page_token` (string) 필드를 must 포함해야 하며, 후속 페이지가 있으면 set, 마지막 페이지이면 must not set 이다	[§Response message] "The `next_page_token` field, which supports pagination, must be included on all list response messages. It must be set if there are subsequent pages, and must not be set if the response represents the final page."	`official-reference`	Google AIP proto List response	본 branch 의 `meta.page.total` 또는 `meta.page.number` 같은 envelope 필드 — AIP-132 는 `total_size` 를 optional (`may`) 로만 정의하며 offset/page 번호를 response 에 요구하지 않음
AIP132-C4	`order_by` 필드 syntax: 기본 ascending, descending 은 `" desc"` suffix 로 표현 (e.g., `"foo desc, bar"`), comma-separated, 공백 무시, subfield 는 dot notation	[§Ordering] "The default sorting order is ascending. To specify descending order for a field, users append a `\" desc\"` suffix; for example: `\"foo desc, bar\"`."	`official-reference`	Google AIP 를 따르는 API 의 `order_by` string field	REST query string 파라미터 명 (`?sort=` vs `?order_by=`) 자체 — AIP-132 는 proto field 명 `order_by` 를 정의하나 URL query param key 명 정규화는 AIP-127. `?sort=-name` (마이너스 prefix 방식) 또는 `?sort=name:desc` (콜론 방식) 는 AIP-132 normative syntax 와 다름
AIP132-C5	List method 의 `filter` 필드는 선택 사항 (`may`) 이며, 포함 시 `string filter` 타입이고 세부 문법은 AIP-160 에서 정의	[§Filtering] "List methods may allow clients to specify filters; if they do, the request message should contain a `string filter` field. Filtering is described in more detail in AIP-160."	`official-reference`	Google AIP 를 따르는 API 의 filtering 기능	filter 문법의 구체 연산자 (예: `AND`, `OR`, 비교 연산자) — 이는 AIP-160 에서 별도 정의됨. 본 claim 은 필드 존재와 AIP-160 참조만 증명
AIP132-C6	List method 의 HTTP verb 는 must `GET` 이어야 하며 이는 safe method 이다 (RFC 9110 §9.2.1 GET is safe)	[§Guidance] "The HTTP verb must be `GET`."	`official-reference`	Google AIP 를 따르는 List endpoint 의 HTTP method	GET 의 safe/idempotent 속성 자체 — 이는 RFC 9110 §9.2.1/9.2.2 normative. AIP-132 는 GET 을 must 로 요구하나 "safe" 또는 "idempotent" 라는 용어 자체는 본 문서에서 명시하지 않음

Strength 확인

AIP-132 는 Google 내부 community guideline (API Improvement Proposals) — IETF RFC 또는 W3C 표준이 아니므로 official-reference (Google 공식 벤더 가이드라인, Google API 설계의 de facto standard). official-standard (RFC/W3C 수준) 아님.

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것

AIP132-C1: List RPC 의 request/response message naming convention (proto 기반)
AIP132-C2: page_size/page_token 이 List request 의 must 필드
AIP132-C3: next_page_token 이 List response 의 must 필드, 유/무 set 의미론
AIP132-C4: order_by 의 normative syntax ("foo desc, bar" 형식, comma-separated, space-insignificant)
AIP132-C5: filter 필드가 optional (may) 이며 AIP-160 에서 문법 정의
AIP132-C6: List method 의 HTTP verb 는 GET 강제

이 자료가 증명하지 않는 것

REST query string 파라미터 명: AIP-132 는 proto field 명을 정의함. page_size → REST query ?page_size= 매핑은 AIP-127 (HTTP/gRPC Transcoding) 범위. 본 branch 의 ?page=N&size=N (camelCase 또는 단축 명) 은 AIP-132 직접 결과 아님 — project-internal 매핑 결정
Sort query param 명: ?sort= vs ?order_by= key 명 자체는 AIP-132 밖. AIP-132 는 proto field 명 order_by 만 정의
Pagination 전략 (offset vs cursor): AIP-132 는 page_size/page_token (cursor-based) 을 정의하나 AIP-132 자체에서 offset-pagination 을 금지하거나 cursor 를 강제하지는 않음. AIP-158 에서 상세 정의
Sort syntax 의 REST 직접 적용: ?sort=name,desc 는 AIP-132 의 "foo,bar" + "foo desc, bar" 를 URL query string 으로 적용한 해석 — AIP-132 본문은 proto field value format 을 정의
?sort=-name (마이너스 prefix 방식) 또는 ?sort=name:desc (콜론 방식): AIP-132 normative 가 아님. " desc" suffix 방식만 normative
Filter 문법의 연산자: AIP-160 범위. 본 자료는 필드 존재와 참조만 언급

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

page_size/page_token → REST ?page=N&size=N 변환의 project-internal 매핑 문서화 — AIP-127 참조 권고
Sort syntax 를 ?sort=name,desc (AIP-132 variant) vs ?sort=-name (OpenAPI community) vs ?sort=name:desc (기타) 중 어느 것으로 채택할지 — D7 미결 B14 의 결정 포인트. AIP-132 기준 채택 시: ?sort=foo desc, bar 또는 URL 인코딩 후 ?order_by=foo+desc%2C+bar 형태가 normative nearest
filter 문법 상세: raw/official-docs/google-aip-160-filtering 신설 후 AIP-160 참조 (현재 미존재)
AIP-158 (Pagination) raw 신설 시 page_token 의 cursor semantics 와 본 branch D7 의 page/size offset pagination 과의 차이 명확화 필요

메모 / Notes

AIP-132 는 proto-first 설계 (gRPC + HTTP transcoding). REST-only API 에 직접 적용 시 proto field 명 → REST query param 변환 규칙 (AIP-127) 을 거쳐야 한다. 본 branch 의 ?page=N&size=N 은 project-internal 선택으로, AIP-132 준수 선언이 아님.
order_by 의 "foo desc, bar" syntax 는 REST query string 에서 ?order_by=foo+desc%2C+bar (URL encoded) 또는 ?sort=foo desc, bar 형태가 될 수 있음. 공백이 URL query string 에서 + 또는 %20 으로 인코딩되는 점을 고려한 API 문서화 필요.
AIP-132 page_size/page_token 기반 pagination 은 cursor-based (opaque token). 본 branch D7 의 offset pagination (page/size) 과 의미론적으로 다름. cursor endpoint 추가 결정 시 AIP-158 참조 권고.
total_size 는 AIP-132 에서 may (optional) — 본 branch 의 meta.page.total 이 이에 대응하지만 AIP-132 가 강제하는 것은 아님.

AIP-158 (Pagination): raw/official-docs/google-aip-158-pagination.md (미신설 — feature-api-contract-baseline §5.2 Next-Session Raw Boost Plan 신설 예정)
AIP-160 (Filtering): raw/official-docs/google-aip-160-filtering.md (미신설 — 신설 예정)
AIP-127 (HTTP/gRPC Transcoding — proto field → REST query param 변환): 미신설
raw/official-docs/google-aip-185-resource-versioning — 동일 AIP 계열, versioning 근거 (D2)
raw/official-docs/api-versioning-google-aip-180 — backward compatibility (D6)
raw/official-docs/jsonapi-pagination-format — pagination link key 명명 표준 (D7)

12 KiB Raw Permalink Blame History Unescape Escape