llm-wiki/raw/official-docs/google-aip-132-list-method.md

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

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

## 출처 / 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 가 강제하는 것은 아님.

## Related / 관련

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