APIs for Agents: Navigating REST, GraphQL, and MCP

Episode summary: For decades, APIs have served as the stable contracts between frontends and backends, but the rise of autonomous AI agents is rewriting the rules of data exchange. This episode dives deep into the fundamental divide between REST's predictable resource-based architecture and GraphQL's flexible, self-documenting graph approach. We explore why the "database-as-an-API" remains a dangerous siren song and how the Model Context Protocol (MCP) acts as a vital translation layer for modern LLMs. From the "token cost" of discovery to the catastrophic risks of the N+1 query problem, we analyze which architecture provides the best "sanity layer" for agents navigating legacy technical debt. Whether you are building fresh tools or wrapping ancient systems, discover how to architect interfaces that empower agents without melting your infrastructure. This is a must-listen for developers looking to bridge the gap between structured data and the unpredictable world of generative AI. Show Notes ### The Evolution of the Digital Contract The history of software development is, in many ways, a history of middlemen. While developers often dream of a "database-as-an-API" model—where clients query data directly without intermediary layers—the reality of production environments requires guardrails. APIs exist to provide three essential pillars: security, stability, and semantics. An API acts as a promise. It creates a stable interface that allows the backend and frontend to evolve independently. This abstraction prevents "leaky abstractions," where the internal mess of a storage engine spills out into the client-side code. If a database schema changes, the API remains the same, ensuring that the application doesn't break every time an engineer optimizes a table or renames a column. ### From RESTful Nouns to GraphQL Relationships For over a decade, REST (Representational State Transfer) dominated the landscape by leaning into the existing architecture of the internet. By using standard HTTP verbs to treat data as resources, REST turned the web into a queryable library of nouns. However, as applications grew in complexity, developers hit the twin walls of over-fetching and under-fetching. GraphQL emerged as a solution to these inefficiencies by moving from resources to graphs. Instead of making multiple sequential requests to different endpoints, GraphQL allows the client to define the exact shape of the data it needs in a single call. This shift turned relationships between data points into first-class citizens, though it introduced new risks, such as the "N+1 query problem," which can inadvertently crash a database through recursive, unoptimized lookups. ### APIs in the Age of AI Agents The rise of Large Language Model (LLM) agents has introduced a new primary consumer for these interfaces. Unlike human developers, agents must "see" and understand an API through documentation or schemas. This is where the technical trade-offs between REST and GraphQL become critical. REST APIs typically rely on external documentation like OpenAPI specifications. These can be massive, outdated, and difficult for an AI to parse without "hallucinating" parameters. In contrast, GraphQL's built-in introspection allows an agent to ask the server for its own schema. This self-documenting nature provides a high-definition map for the agent, significantly lowering the "token cost" of discovery. ### The Model Context Protocol (MCP) and the Sanity Layer The Model Context Protocol (MCP) is emerging as the translation layer between these two worlds. It doesn't favor one architecture over the other but instead focuses on how "tools" are exposed to an agent. While REST offers a narrow, predictable corridor of behavior that is easier to rate-limit and secure, GraphQL offers the flexibility for an agent to act as a creative data scientist. For many organizations, the real value of MCP lies in its ability to act as a "sanity layer." Most enterprise systems are not clean; they are a patchwork of legacy REST APIs and ancient databases. By building an MCP server, developers can wrap this technical debt in a modern, structured interface. This allows the AI agent to operate in a clean, simulated environment while the underlying server handles the messy translation to legacy systems. Ultimately, the goal is to reduce the "agentic friction" of the modern web, creating a world where automation can navigate complex infrastructure safely and efficiently. Listen online: https://myweirdprompts.com/episode/api-evolution-ai-agents