AIP Knowledge
Quick reference for API Improvement Proposals adapted to REST/OpenAPI.
When to Load References
Based on the task, load the relevant reference file:
| Topic |
Reference File |
When to Use |
| Error responses |
errors.md |
Designing error schema, reviewing error handling |
| Pagination |
pagination.md |
Adding pagination to list endpoints |
| Filtering & sorting |
filtering.md |
Adding filter/order_by parameters |
| Long-running ops |
lro.md |
Async operations, jobs, polling |
| Partial updates |
field-masks.md |
PATCH implementation, update semantics |
| Batch operations |
batch.md |
Batch create/update/delete |
| Proto → REST mapping |
rest-mapping.md |
Translating AIP concepts to REST |
Implemented Linter Rules
The AIP reviewer includes 17 automated rules across 6 categories:
Naming (AIP-122)
| Rule ID |
Severity |
What It Checks |
aip122/plural-resources |
warning |
Resource paths use plural nouns |
aip122/no-verbs |
error |
Paths contain nouns, not verbs |
aip122/consistent-casing |
warning |
Path segments use consistent casing (kebab, snake, camel) |
aip122/nested-ownership |
suggestion |
Nested resource params have descriptive names (not just {id}) |
Standard Methods (AIP-131 to 135)
| Rule ID |
Severity |
What It Checks |
aip131/get-no-body |
error |
GET requests have no request body |
aip133/post-returns-201 |
suggestion |
POST returns 201 Created or 202 Accepted |
aip134/patch-over-put |
suggestion |
PATCH available for partial updates (not just PUT) |
aip135/delete-idempotent |
warning |
DELETE has no body and uses standard status codes |
Pagination (AIP-158)
| Rule ID |
Severity |
What It Checks |
aip158/list-paginated |
warning |
List endpoints have page_size and page_token params |
aip158/max-page-size |
suggestion |
page_size param has maximum constraint |
aip158/response-next-token |
warning |
Paginated responses include next_page_token field |
Filtering (AIP-132, 160)
| Rule ID |
Severity |
What It Checks |
aip132/has-filtering |
suggestion |
List endpoints document filter parameters |
aip132/has-ordering |
suggestion |
List endpoints support order_by parameter |
Errors (AIP-193)
| Rule ID |
Severity |
What It Checks |
aip193/schema-defined |
warning |
Error schema defined in components |
aip193/responses-documented |
suggestion |
Operations document error responses |
aip193/standard-codes |
suggestion |
Standard HTTP error codes used (400, 401, 403, 404, etc.) |
Idempotency (AIP-155)
| Rule ID |
Severity |
What It Checks |
aip155/idempotency-key |
suggestion |
POST endpoints accept Idempotency-Key header |
Topics Without Automated Rules (Reference Only)
The following topics have detailed reference documentation but no automated linter rules yet:
- Field Masks (
field-masks.md) - AIP-134 partial update patterns (only aip134/patch-over-put checks for PATCH availability)
- Batch Operations (
batch.md) - AIP-231+ batch patterns
- Long-Running Operations (
lro.md) - AIP-151, 155 async patterns
- Proto → REST Mapping (
rest-mapping.md) - Translation guide
Quick Reference
Standard Methods → HTTP
| Method |
HTTP |
Path |
Idempotent |
Related Rules |
| Get |
GET |
/resources/{id} |
Yes |
aip131/get-no-body |
| List |
GET |
/resources |
Yes |
aip158/list-paginated, aip132/has-filtering, aip132/has-ordering |
| Create |
POST |
/resources |
No* |
aip133/post-returns-201, aip155/idempotency-key |
| Update |
PATCH |
/resources/{id} |
Yes |
aip134/patch-over-put |
| Delete |
DELETE |
/resources/{id} |
Yes |
aip135/delete-idempotent |
*Use Idempotency-Key header for safe retries
Naming Rules (AIP-122)
/users, /orders, /products (plural nouns)/user, /order (singular - triggers aip122/plural-resources)/getUsers, /createOrder (verbs - triggers aip122/no-verbs)/users/{id}/orders (nested ownership)
Pagination (AIP-158)
Request: ?page_size=20&page_token=xxx
Response:
{
"data": [...],
"next_page_token": "yyy"
}
Error Response (AIP-193)
{
"error": {
"code": "INVALID_ARGUMENT",
"message": "Human-readable message",
"details": [...],
"request_id": "req_abc123"
}
}
Fetch AIPs On Demand
For detailed guidance, fetch from:
https://google.aip.dev/{number} (e.g., /158 for pagination)- Only fetch when user needs deeper explanation
1---2name: aip-knowledge3description: Reference knowledge for Google API Improvement Proposals (AIP), adapted for REST/OpenAPI. Use when reviewing APIs, designing endpoints, or explaining AIP rules. Contains patterns for errors, pagination, filtering, LRO, field masks, and batch operations.4---5
6# AIP Knowledge
7
8Quick reference for API Improvement Proposals adapted to REST/OpenAPI.
9
10## When to Load References
11
12Based on the task, load the relevant reference file:
13
14| Topic | Reference File | When to Use |
15| -------------------- | ----------------- | ------------------------------------------------ |
16| Error responses | `errors.md` | Designing error schema, reviewing error handling |
17| Pagination | `pagination.md` | Adding pagination to list endpoints |
18| Filtering & sorting | `filtering.md` | Adding filter/order_by parameters |
19| Long-running ops | `lro.md` | Async operations, jobs, polling |
20| Partial updates | `field-masks.md` | PATCH implementation, update semantics |
21| Batch operations | `batch.md` | Batch create/update/delete |
22| Proto → REST mapping | `rest-mapping.md` | Translating AIP concepts to REST |
23
24## Implemented Linter Rules
25
26The AIP reviewer includes 17 automated rules across 6 categories:
27
28### Naming (AIP-122)
29
30| Rule ID | Severity | What It Checks |
31| -------------------------- | ---------- | --------------------------------------------------------------- |
32| `aip122/plural-resources` | warning | Resource paths use plural nouns |
33| `aip122/no-verbs` | error | Paths contain nouns, not verbs |
34| `aip122/consistent-casing` | warning | Path segments use consistent casing (kebab, snake, camel) |
35| `aip122/nested-ownership` | suggestion | Nested resource params have descriptive names (not just `{id}`) |
36
37### Standard Methods (AIP-131 to 135)
38
39| Rule ID | Severity | What It Checks |
40| -------------------------- | ---------- | -------------------------------------------------- |
41| `aip131/get-no-body` | error | GET requests have no request body |
42| `aip133/post-returns-201` | suggestion | POST returns 201 Created or 202 Accepted |
43| `aip134/patch-over-put` | suggestion | PATCH available for partial updates (not just PUT) |
44| `aip135/delete-idempotent` | warning | DELETE has no body and uses standard status codes |
45
46### Pagination (AIP-158)
47
48| Rule ID | Severity | What It Checks |
49| ---------------------------- | ---------- | --------------------------------------------------- |
50| `aip158/list-paginated` | warning | List endpoints have page_size and page_token params |
51| `aip158/max-page-size` | suggestion | page_size param has maximum constraint |
52| `aip158/response-next-token` | warning | Paginated responses include next_page_token field |
53
54### Filtering (AIP-132, 160)
55
56| Rule ID | Severity | What It Checks |
57| ---------------------- | ---------- | ----------------------------------------- |
58| `aip132/has-filtering` | suggestion | List endpoints document filter parameters |
59| `aip132/has-ordering` | suggestion | List endpoints support order_by parameter |
60
61### Errors (AIP-193)
62
63| Rule ID | Severity | What It Checks |
64| ----------------------------- | ---------- | --------------------------------------------------------- |
65| `aip193/schema-defined` | warning | Error schema defined in components |
66| `aip193/responses-documented` | suggestion | Operations document error responses |
67| `aip193/standard-codes` | suggestion | Standard HTTP error codes used (400, 401, 403, 404, etc.) |
68
69### Idempotency (AIP-155)
70
71| Rule ID | Severity | What It Checks |
72| ------------------------ | ---------- | -------------------------------------------- |
73| `aip155/idempotency-key` | suggestion | POST endpoints accept Idempotency-Key header |
74
75## Topics Without Automated Rules (Reference Only)
76
77The following topics have detailed reference documentation but no automated linter rules yet:
78
79- **Field Masks** (`field-masks.md`) - AIP-134 partial update patterns (only `aip134/patch-over-put` checks for PATCH availability)
80- **Batch Operations** (`batch.md`) - AIP-231+ batch patterns
81- **Long-Running Operations** (`lro.md`) - AIP-151, 155 async patterns
82- **Proto → REST Mapping** (`rest-mapping.md`) - Translation guide
83
84## Quick Reference
85
86### Standard Methods → HTTP
87
88| Method | HTTP | Path | Idempotent | Related Rules |
89| ------ | ------ | ----------------- | ---------- | ---------------------------------------------------------------------- |
90| Get | GET | `/resources/{id}` | Yes | `aip131/get-no-body` |
91| List | GET | `/resources` | Yes | `aip158/list-paginated`, `aip132/has-filtering`, `aip132/has-ordering` |
92| Create | POST | `/resources` | No\* | `aip133/post-returns-201`, `aip155/idempotency-key` |
93| Update | PATCH | `/resources/{id}` | Yes | `aip134/patch-over-put` |
94| Delete | DELETE | `/resources/{id}` | Yes | `aip135/delete-idempotent` |
95
96\*Use Idempotency-Key header for safe retries
97
98### Naming Rules (AIP-122)
99
100- `/users`, `/orders`, `/products` (plural nouns)
101- `/user`, `/order` (singular - triggers `aip122/plural-resources`)
102- `/getUsers`, `/createOrder` (verbs - triggers `aip122/no-verbs`)
103- `/users/{id}/orders` (nested ownership)
104
105### Pagination (AIP-158)
106
107Request: `?page_size=20&page_token=xxx`
108
109Response:
110
111```json
112{
113 "data": [...],
114 "next_page_token": "yyy"
115}
116```
117
118### Error Response (AIP-193)
119
120```json
121{
122 "error": {
123 "code": "INVALID_ARGUMENT",
124 "message": "Human-readable message",
125 "details": [...],
126 "request_id": "req_abc123"
127 }
128}
129```
130
131### Fetch AIPs On Demand
132
133For detailed guidance, fetch from:
134
135- `https://google.aip.dev/{number}` (e.g., `/158` for pagination)
136- Only fetch when user needs deeper explanation
majiayu000