aip-knowledge
Google API改进提案(AIP)的参考知识,适应REST/OpenAPI。在审查API、设计端点或解释AIP规则时使用。包含错误、分页、过滤、LRO、字段掩码和批处理操作的模式。
📖 中文导读:Google API改进提案(AIP)的参考知识,适应REST/OpenAPI。在审查API、设计端点或解释AIP规则时使用。包含错误、分页、过滤、LRO、字段掩码和批处理操作的模式。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: aip-knowledge description: This skill should be used when the user asks about "AIP rules", "API Improvement Proposals", "Google API guidelines", "AIP-158", "AIP-193", or any specific AIP number. Also use when user asks "how should I implement pagination", "what's the right error format", "how do I design a REST API following Google's standards", or needs guidance on errors, pagination, filtering, field masks, long-running operations, or batch operations in REST/OpenAPI APIs.
AIP Knowledge
Quick reference for 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
aip-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