Design Declarative-Friendly APIs
summary
Explains concrete API rules that make declarative clients reliable: enforce a consistent create/read/update/delete surface with strong read-after-write, avoid or expose user-settable IDs, and separate server-managed fields into a read-only status (or a distinct duplex field) to prevent reconcile loops. Cites thousands of Terraform provider issues from inconsistent APIs, shows Kubernetes CRDs as a near-ideal pattern, and describes an open-source A.D. spec (Google, Roblox, IBM, Microsoft, Netflix contributors) and tooling to generate standard declarative clients.
AI-written summary · about
chapters (10)
- 0:00Introduction
- 1:27Declarative clients matter
- 3:53Reconciliation loop
- 6:05Design patterns
- 9:17Strong consistency
- 11:04User-settable identifiers
- 13:31Primitive loops problem
- 16:21Mixed management solutions
- 18:28Declarative-friendly API example
- 20:35Future directions
related talks
41mThe making of a great API
34mDesign Principles: API vs MCP
54mEffective Design of RESTful APIs
01h 36mThe Most Important API Design Guideline - No, It's Not That One
24mGraphQL, gRPC, REST, Oh My! - A Method for Unified API Design
33mDesigning Sustainable APIs
01h 06mGood API design
49mPoor API design is not sustainable.