API Design for the Decade: Contracts, Versioning and the AI Consumer
Suresh Venkatesan
Principal Engineer, RippleCode
APIs outlive the applications they were built for. The interfaces we design today will be consumed by web apps, mobile clients, partner integrations and — increasingly — AI agents that read documentation and call endpoints autonomously. That last consumer changes some old rules.
Contract-first, forever
Schema-first design (OpenAPI, GraphQL SDL) remains the foundation: generated clients, automated validation, documentation that can't drift from reality. The new beneficiary is AI — agents consume typed contracts far more reliably than prose documentation.
Design for the confused consumer
- Error messages that say what went wrong and what to do about it
- Consistent naming and predictable resource patterns across the entire surface
- Idempotency keys on anything that mutates — agents retry
- Explicit rate limits with standard headers, not silent throttling
Versioning: boring wins
Additive changes without version bumps; breaking changes behind new versions with long, published deprecation windows. The exotic strategies (per-field versioning, content negotiation gymnastics) generate more confusion than compatibility.
The agent-readiness test
Could an LLM, given only your API spec, complete a real task without human help? That test surfaces every ambiguity: vague parameter names, undocumented preconditions, error responses that don't guide recovery. Fixing them helps humans exactly as much as machines.