saltbo/agent-laws/api-design

Designing an API

The how-to for API design, in depth. The binding standard is the API Design Law (API-001–API-011); this skill is how you satisfy it. If guidance here ever conflicts with the Law, the Law wins and this skill is fixed.

It follows [Google AIP](https://google.aip.dev). This file is the map; the detail lives in `reference/` — open the chapter for the task at hand and follow it.

Chapters

The core in one screen

• Model resources (nouns), not endpoints. A small standard method set — Get, List, Create, Update (PATCH), Delete — plus custom methods (POST /orders/{id}:cancel) for the rest. Don't mirror the database. → API-004
• Name predictably. collection/{id}/collection/{id}; plural camelCase collections; DNS-safe ids; one casing for fields. → API-004
• Version up front; evolve additively. One live version, guarded by a CI schema-diff. → API-001/API-002
• Errors are `google.rpc.Status` with an ErrorInfo whose (reason, domain) is the machine-readable identity; correct code→HTTP. → API-003
• Paginate everything that grows (page_size/page_token/next_page_token, server-capped). → API-005
• Reads are safe; risky writes are idempotent. → API-006
• Validate and authorize at the edge. → API-007, API-010
• Contract-first (OpenAPI/proto), drift-checked in CI. → API-008

Pre-ship checklist

• [ ] Versioned; CI schema-diff guards breaking changes (API-001, API-002)
• [ ] google.rpc.Status errors with ErrorInfo; correct code→HTTP (API-003)
• [ ] Resource-oriented surface; standard methods; predictable names (API-004)
• [ ] Lists paginated and capped (API-005)
• [ ] Reads safe; risky writes idempotent (API-006)
• [ ] Inputs validated and authorized at the edge (API-007, API-010)
• [ ] Machine-readable contract, drift-checked in CI (API-008)
• [ ] Deprecations signaled with a sunset date (API-009)
• [ ] Unambiguous data formats (API-011)

References

Google AIP (primary) · Google Cloud API Design Guide · Zalando RESTful API Guidelines · Microsoft/Azure REST API design · OpenAPI 3.1 · RFC 9457 Problem Details.