aip-knowledge

getlarge 的头像作者 getlarge

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

  1. For quick patterns: Use the Quick Reference section below
  2. For detailed guidance: Load the relevant reference file from the table
  3. For AIP rule violations: See linter-rules.md for all 17 automated rules
  4. For deeper explanation: Use the aip-lookup agent 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 - 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