aip-knowledge

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 Google 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 baume-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