Where randomness meets reason

Office Hours — Why don't AI coding tools like REST? A daily developer question about AI/LLMs, answered with a direct, opinionated take. 2026-05-16T12:00:00.000Z Office Hours Office Hours office-hoursq-and-apractical-ai

Office Hours — Why don't AI coding tools like REST?

A daily developer question about AI/LLMs, answered with a direct, opinionated take.

office-hoursq-and-apractical-ai
Daily One question from the trenches, one opinionated answer.

Why don’t AI coding tools like REST?

REST is foundational infrastructure for web APIs. It’s predictable, stateless, and easy to reason about. So why do coding agents, autonomous systems, and LLM-powered tools treat REST like it’s optional scaffolding instead of a first-class integration target?

The short answer: REST’s constraints make it harder for AI systems to accomplish what they actually need to do. And as coding agents move from “write this function” into “deploy this change to production,” the friction becomes real.

The REST Problem for Agents

REST assumes a human is orchestrating the conversation. You call /users/{id}, you get back a response, you decide what to do next. The human reads the schema docs, understands the semantics, and knows what 404 means in context.

Agents don’t work that way. When Claude Code or GitHub Copilot integrates with your infrastructure, it needs to:

Discover what’s actually possible without reading 50 pages of OpenAPI specs. Most REST APIs document themselves for humans, not machines. “Create a deployment” might be POST /deployments, but it might also require you to understand versioning semantics, required headers, eventual consistency behavior, or state machine constraints that aren’t in the schema at all.

Handle failure modes that REST doesn’t express cleanly. A 202 Accepted response doesn’t tell an agent whether to poll, webhook, or just assume the job completed. A 429 Rate Limit response doesn’t tell the agent whether to retry in 30 seconds or 30 minutes. A 500 Internal Server Error doesn’t distinguish between “try again immediately” and “this is broken, escalate to a human.”

Understand what actions are safe to retry. REST conflates idempotence with safety. An agent doesn’t know if POST /payments is safe to retry after a timeout without deeply understanding the resource semantics, which REST doesn’t guarantee.

Manage state across multiple calls when the state machines are implicit. Deploying code involves multiple steps: build, test, push, deploy, monitor. REST gives you endpoints for each, but doesn’t express the dependency graph or what happens if step 3 fails midway. An agent has to infer the state machine from trial and error or documentation.

What Agents Actually Want

This is why you see coding agents gravitating toward:

GraphQL (better discovery, explicit schemas that tools can parse). Webhook systems and event buses (async state changes that agents can react to, instead of polling). Structured APIs with explicit error codes and retry semantics (like gRPC). Tool-use protocols like Model Context Protocol (MCP) that let agents ask “what can I do?” and get back a machine-readable capability manifest.

None of these replace REST entirely. But they solve problems REST doesn’t, and as agents move into critical paths, those problems become expensive.

A Concrete Example

You want Claude Code to deploy your service to Kubernetes. Claude needs to:

  1. Get the current deployment state
  2. Build a new image
  3. Push to a registry
  4. Update the deployment
  5. Wait for rollout
  6. Verify health

With REST, Claude is making five separate calls to five endpoints, each with implicit assumptions about timing and state. If the image push takes 30 seconds longer than expected, Claude might check rollout status before the image is even available, get a confusing error, and give up or retry incorrectly.

With an async event system (CloudEvents, Kubernetes events, or a proper agentic API), Claude submits a high-level intent (“deploy this image”), gets back a watch handle, subscribes to state change events, and reacts when the actual state changes. No polling. No guessing about timing. The system tells Claude exactly what happened and why.

REST can be wrapped with polling logic and retry semantics, but that’s what agents are doing anyway. They’re building a higher-level abstraction on top because REST doesn’t provide it natively.

Why REST Persists Despite This

REST won because it’s simple for humans to understand and build. A frontend engineer can eyeball a REST endpoint and know roughly what it does. That simplicity is real value.

But agents don’t read the eyeballs. They read the specs. And when the spec is incomplete (which it usually is for implicit behavior), agents fail in ways that are hard to debug.

If you’re building infrastructure that agents will touch, REST is fine for read-heavy, simple operations. But for state changes, multi-step workflows, or anything where failure modes matter, you’re doing yourself a favor by adding event systems, async callbacks, or structured agentic APIs on top.

The tools aren’t avoiding REST out of stubbornness. They’re routing around it because REST was designed for a different problem: stateless HTTP requests from browsers. Coding agents need state machines, observability, and failure semantics. REST gives you none of those.

Bottom line: If you’re designing APIs that agents will call, invest in explicit error codes, async state notifications, and machine-readable capability discovery. REST can coexist with those, but don’t expect agents to thrive on REST alone.

Question via Hacker News