Requirements for AI-Native API Design

In the past, we tended to design APIs to be high-level and abstract. This is an ergonomic UX choice, because we expect human users to be lazy, to like preset values, and to be goal-oriented. The drawback of high-level APIs is also obvious: they lose flexibility, and complex parameter combinations get hidden away.

But AI is different from humans. It tends to fill in every parameter it can. It does not mind spending a few more tokens, so ergonomic UX is meaningless to it. This means APIs for AI should be highly composable and low-level enough to support direct operations.

The contrast can also be described as the difference between MCP and skills: the former is built in an OpenAPI style, so its habit is high-level; the latter is built in a shell style, so its habit is low-level.

In fact, the best practice has not changed: good abstractions, sufficiently orthogonal parameters, and reasonable defaults. For both AI and humans, these reduce mental overhead while preserving flexibility.

This matters especially when one API may need to serve both humans and AI. For example, when I design agent memories, I need to force-inject some memories in code while also allowing the agent to query memories on its own.

The best practice has not changed. AI only reminds me that it matters even more.

Note: in this article, AI refers to LLM agents.