Five design shifts separate intent-based APIs from classic REST: contracts, planners, tools, policy, evals, metrics, and guardrails. Read now.
From Endpoints to Goals
Classic REST asks the caller to know the mechanics: which endpoint to hit, in what order, and how to stitch the responses together to reach an outcome. An intent-based API inverts that burden. The caller states what it wants — the goal — and the service works out the steps. Instead of "create a record, then attach a line item, then submit," the request expresses the destination and leaves the route to the server.
This shift only works if the goal is expressed precisely. That is why the contract moves to the center of the design, and why the pieces around it — planning, tool execution, policy, and measurement — become first-class concerns rather than implementation details.
The Five Shifts
Moving from REST to semantic goals is not a single change but a set of related ones. Each replaces something the caller used to do with something the service now owns.
- Contracts describe intents and acceptable outcomes rather than fixed request/response shapes, so callers commit to what not how.
- Planners decompose a stated goal into an ordered sequence of concrete steps, choosing the path at request time.
- Tools are the underlying operations a planner composes — often the same primitives your REST layer already exposes.
- Policy decides which plans and tools are permitted for a given caller and context, separate from whether they are technically possible.
- Evals and metrics judge whether the produced outcome actually satisfied the intent, closing the loop that a status code alone cannot.
Why Contracts and Planners Change Most
In REST, the contract is a schema: shapes and field types. In an intent-based API, the contract also has to pin down what "done" means for each intent — the conditions that count as success, the outputs the caller can rely on, and the failure states it must handle. Vague goals produce vague plans, so the contract does more work than a schema ever did.
The planner is where correctness is won or lost. Because it chooses steps dynamically, two identical requests can take different paths, which makes reproducibility and auditability harder than in a fixed endpoint. Treat plans as inspectable artifacts: log the chosen steps, make them reviewable, and let callers see how a goal was reached rather than only the final answer.
Governing Behavior: Policy, Evals, and Guardrails
When the service decides its own steps, you need controls the caller can no longer enforce. Policy constrains which tools and plans are available per caller and per context, so capability and permission stay distinct. Guardrails bound what the planner may attempt at all — blocking destructive or out-of-scope actions before they run, not after.
Evals and metrics tell you whether any of it is working. Track how often a stated intent was genuinely satisfied, where planners chose poor paths, and which tools fail under load. Keep these signals close to the contract's definition of success so the numbers measure outcomes, not just uptime. Without that feedback, an intent-based API is just indirection; with it, the service can be tuned toward the goals callers actually asked for.