AIP Knowledge
Quick reference for Google API Improvement Proposals adapted to REST/OpenAPI.
How to Use This Skill
- For quick patterns: Use the Quick Reference section below
- For detailed guidance: Load the relevant reference file from the table
- For AIP rule violations: See
linter-rules.mdfor all 17 automated rules - For deeper explanation: Use the
baume-lookupagent to fetch from google.aip.dev
Reference Files
Load the relevant reference file based on the task:
| 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 |
| Linter rules | linter-rules.md | All 17 automated AIP rules with skip options |
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 - triggersaip122/plural-resources)/getUsers,/createOrder(verbs - triggersaip122/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.,/158for pagination)- Only fetch when user needs deeper explanation