API Design Principles for the AI Era

API design was once primarily about developer experience — how quickly can a human engineer understand the contract, write the client code, and integrate? That constraint still matters. But in 2025, your APIs are increasingly being consumed by AI agents that don't read documentation, don't parse error messages the way humans do, and will call your API in ways your team never anticipated.

The LLM-as-API-consumer problem

When an LLM agent calls your API, it reasons about what parameters to send based on a description — typically a function signature, a brief docstring, or an OpenAPI schema. Ambiguous field names, overloaded endpoints, and implicit state requirements are catastrophic for agents. What's a minor annoyance for a human developer is a hard failure mode for an LLM.

Principle 1: Semantically dense schemas

Every field in your API schema should carry its meaning in its name, type, and description — with no reliance on out-of-band documentation. If a field called `status` can mean 14 different things depending on the resource type, an agent will misuse it. Prefer explicit enumerations (`order_fulfillment_status: 'pending' | 'processing' | 'dispatched' | 'delivered' | 'cancelled'`) over generic strings. Describe constraints in the schema itself — min/max values, regex patterns, business rules.

Principle 2: Idempotency everywhere

LLM agents retry. They lose track of whether a call succeeded. They may issue the same write operation multiple times due to reasoning errors or network conditions. Every state-mutating endpoint should be idempotent — either by design (PUT over POST for creation) or by idempotency key. Document idempotency behaviour explicitly in the schema, not just in the developer portal.

Principle 3: Structured errors, not status codes

A 422 Unprocessable Entity tells a human developer to look at the response body. An LLM agent needs the error body to be self-describing, actionable, and consistent. Define a standard error envelope (`code`, `message`, `field`, `suggestion`) and return it consistently across every endpoint. Agents can be prompted to retry with corrected parameters when errors are structured — not when they're free-form strings.

Principle 4: Capability discovery

REST APIs are discovered by reading OpenAPI specs or documentation. GraphQL APIs are discoverable via introspection. For agent-first APIs, go further: implement a `/.well-known/api-capabilities` endpoint that returns a machine-readable description of what your API can do, what data it operates on, and what permissions are required. This enables agents to reason about whether your API can serve their goal before attempting calls.

Principle 5: Observability at the call level

Agent-driven API traffic has different patterns than human-driven traffic. You'll see bursts of similar calls as an agent explores your API surface, unusual parameter combinations, and retry storms when agents encounter ambiguous responses. Build agent-specific observability: log the caller's agent identifier, track call sequences rather than just individual calls, and alert on patterns that suggest agent confusion (rapid retry loops, consistent parameter errors).

The MCP moment

Model Context Protocol (MCP) is emerging as the standardisation layer for agent-API communication. If your API surfaces are likely to be consumed by Claude, GPT-4, or Gemini agents in a tool-use context, investing in MCP server implementations today will pay dividends as the ecosystem matures. The underlying API design principles are the same — but MCP provides the transport and capability description layer.

Backwards compatibility still matters

None of this replaces the existing rules of good API design: semantic versioning, graceful deprecation, backwards-compatible evolution, and stable contracts. The AI era adds new constraints — it doesn't remove the old ones. An API that's great for human developers and hostile to agents, or vice versa, is a design failure.