← Back to principles

API

Design for autonomous consumers

What this means in practice

Design public APIs so that the primary consumer can be automation first: agents, workflows, and AI systems that need clear intent, stable structure, and low ambiguity. The API should still be usable by humans, but it should not rely on human intuition or undocumented context to be used correctly. Endpoints and payloads should be modelled around meaningful tasks and outcomes, not raw data exposure.

Why this matters

Autonomous consumers amplify both good and bad API design. When interfaces are explicit and contextual, integrations become easier to build, more resilient to change, and cheaper to operate. It reduces back-and-forth support, prevents misuse, and enables higher-leverage automation. It also improves human developer experience, because clear intent and good defaults help everyone.

Practices that meet this principle

  • Provide documentation that is complete, structured, and machine-consumable (for example: OpenAPI kept up to date, consistent examples, stable error taxonomy)

  • Design endpoints around intent and workflows, not tables (for example: time entries by week rather than by day when that matches how consumers reason and operate)

  • Prefer explicit parameters and well-defined enums over free-text inputs where possible

  • Use consistent naming, pagination, filtering, and error shapes across the API surface

  • Return actionable validation errors that make it easy for automated clients to recover

  • Include idempotency and safe retry semantics for operations that may be repeated by automation

  • Where appropriate, make workflows discoverable (for example: documented link relations / HATEOAS-style cues for next actions)

Validation

A project meets this principle when:

  • A new consumer can implement a reliable integration using only the contract and documentation, without bespoke guidance

  • Common workflows are supported via contextual endpoints rather than requiring consumers to reconstruct intent from raw data

  • The API is unambiguous enough for automated clients to use correctly (for example: clear schemas, stable semantics, documented errors)

  • Documentation, schemas, and examples stay in sync with production behaviour