GraphQL vs REST for Agent Readiness: Which API Style Agents Prefer
REST and GraphQL solve the same problem differently — and AI agents interact with each in fundamentally different ways. REST is easier to discover. GraphQL is more powerful to use. After scanning 500 businesses, here is how each style maps to the 9 dimensions of agent readiness, and what to offer if you want maximum coverage.
Why API Style Matters for Agents
When a human developer integrates with an API, they read documentation once and write code that runs forever. When an AI agent interacts with an API, it discovers, understands, and calls the API at runtime — every time. This makes the API style a first-class factor in agent readiness.
REST APIs expose a collection of URL endpoints, each representing a resource. An agent discovers them via an OpenAPI spec (a single JSON or YAML file listing every endpoint, parameter, and response schema). The agent reads the spec, picks the right endpoint, and makes an HTTP call. The model is simple: one URL, one resource, one action.
GraphQL APIs expose a single endpoint with a typed schema. An agent discovers the schema via an introspection query — essentially asking the API “what can you do?” The agent then constructs a query in GraphQL syntax, specifying exactly which fields it needs across potentially nested relationships. The model is flexible but requires the agent to understand a query language.
Both work. Both have strengths. The question for agent readiness is: which style maps better to each dimension of the scoring model?
- Predictable URL-per-resource pattern
- OpenAPI spec = instant discovery
- HTTP verbs = clear intent (GET reads, POST creates)
- Status codes signal outcome directly
- Ask for exactly the fields you need
- Nested relationships in one request
- Introspection = self-documenting schema
- Strongly typed everything
Dimension-by-Dimension: REST vs GraphQL
How each API style maps to the 6 most relevant dimensions of the Agent Readiness Score.
D1 Discoverability (12%)
RESTOpenAPI spec at well-known URL. Agents find endpoints via /openapi.json or /swagger.json. Standard tooling parses it instantly.
Single /graphql endpoint. Discoverable, but agents need to know to send an introspection query to learn the schema.
D2 API Quality (15%)
GraphQLOne endpoint per resource. Predictable URL patterns (/users/123). GET/POST/PUT/DELETE semantics. Limited to predefined response shapes.
Flexible queries return exactly the fields needed. No over-fetching. Nested relationships in one request. Typed schema.
D3 Onboarding (8%)
RESTcurl-friendly. An agent can test with a single HTTP request. No query language to learn. Widely understood by LLMs.
Requires constructing queries in GraphQL syntax. Agents must understand the query language. Mutations need specific input types.
D6 Data Quality (10%)
GraphQLFixed response shapes. Consistent structure across calls. Easy to validate against OpenAPI schemas.
Response shape matches query. Always typed. Introspection provides complete schema with descriptions for every field.
D7 Security (12%)
RESTBearer token in header. Per-endpoint authorization is straightforward. Scoped API keys map to endpoint groups.
Same Bearer token, but authorization must be field-level. Complex nested queries can create authorization gaps.
D9 Agent Experience (10%)
TiePagination, rate-limit headers, idempotency keys all have established patterns. Agents know what to expect.
Relay-style cursor pagination is excellent. Errors in the response body (not HTTP status). Custom extensions for rate limits.
The scorecard: REST wins on 3 dimensions (D1, D3, D7) weighted at 32% combined. GraphQL wins on 2 dimensions (D2, D6) weighted at 25% combined. D9 is a tie. For pure agent readiness scoring, REST with OpenAPI has a slight edge — but GraphQL adds power for sophisticated agents.
Case Study: GitHub Offers Both (Score: 67 Silver)
GitHub is one of the few companies offering both REST and GraphQL APIs at scale. Their Agent Readiness Score of 67 (Silver) benefits from this dual approach. Here is how each API performs for agent use cases.
The takeaway: GitHub's REST API is what most agents use for simple operations — list repos, read files, create issues. The GraphQL API is what sophisticated agents use when they need to traverse the object graph — “get me the last 5 PRs for this repo with their review comments and CI check results” in a single request.
Offering both is the optimal strategy. The REST API with OpenAPI spec handles discovery and simple operations. The GraphQL API handles complex, relationship-heavy queries that would require 5-10 REST calls.
The Best Practice: REST for Discovery, GraphQL for Power
If you are building from scratch and can only offer one, choose REST with a published OpenAPI spec. The discovery advantage is too important — agents cannot use what they cannot find, and OpenAPI is the universal discovery mechanism for REST APIs.
If you already have a GraphQL API, do not remove it. Instead, add these three things to maximize your score:
Keep introspection enabled (or provide a schema file)
Disabling introspection in production is a common security recommendation, but it removes the primary discovery mechanism for agents. If you must disable it, publish the schema as a downloadable file at a well-known URL.
Add descriptions to every type and field
GraphQL introspection includes description fields on types, fields, and arguments. These descriptions are what agents read to understand what each field means. A schema without descriptions is like an API without documentation.
Publish an OpenAPI spec for a REST wrapper (or core endpoints)
Even if your primary API is GraphQL, expose the most common operations as REST endpoints with an OpenAPI spec. This gives agents the simple discovery path while keeping GraphQL available for advanced use.
The ideal architecture for agent readiness is what GitHub, Shopify, and the top-scoring platforms do: REST with OpenAPI for discovery and basic CRUD, GraphQL for flexible queries and complex data retrieval. This combination scores well on every dimension because it gives agents two paths — a simple one and a powerful one.
MCP Supersedes Both (But Needs a Backend)
There is a third option emerging: MCP servers. The Model Context Protocol does not care whether your backend is REST or GraphQL. An MCP server exposes tools that agents call by name, with typed inputs and outputs. The tool implementation can call REST, GraphQL, gRPC, or a database directly.
For agent readiness scoring, an MCP server adds 5-8 points on top of whatever your underlying API style provides. The agent-native bonus (D10, 7% weight) specifically rewards MCP adoption. Combined with auto-generated SDKs from your OpenAPI spec, the triple stack of REST + GraphQL + MCP gives agents maximum flexibility.
But MCP needs a backend. If you have neither REST nor GraphQL today, start with REST and OpenAPI — it is the fastest path to agent discovery. Then layer MCP on top for the agent-native bonus.
Frequently Asked Questions
Should I pick GraphQL or REST for agent readiness?
If you can only offer one, choose REST with an OpenAPI spec. REST is easier for agents to discover, authenticate against, and use without specialized knowledge. The LLMs powering most AI agents have seen far more REST API documentation in training data than GraphQL schemas. However, if you already have GraphQL, do not remove it — add an OpenAPI spec for REST discovery and keep GraphQL for agents that can leverage its power.
Can AI agents actually write GraphQL queries?
Yes, modern LLMs (GPT-4, Claude, Gemini) can generate syntactically correct GraphQL queries when given a schema. The challenge is not generation — it is discovery. An agent needs to first find the GraphQL endpoint, then run an introspection query to get the schema, then understand the domain-specific types well enough to construct a useful query. REST with OpenAPI lets agents skip the first two steps entirely.
How does AgentHermes scan for GraphQL endpoints?
AgentHermes checks for /graphql, /api/graphql, and /gql endpoints. If found, it sends an introspection query to evaluate the schema completeness, type descriptions, and authentication requirements. The introspection results contribute to D2 API Quality and D6 Data Quality scores. Disabled introspection (common in production for security) actually reduces the agent readiness score because agents cannot self-discover the API surface.
What about tRPC, gRPC, or other API styles?
gRPC uses Protocol Buffers with strong typing, but requires HTTP/2 and binary encoding — most AI agents expect HTTP/1.1 and JSON. tRPC is TypeScript-specific and relies on build-time type sharing, which agents cannot leverage at runtime. For agent readiness specifically, REST with OpenAPI and GraphQL with introspection are the two styles that agents can discover and use without prior integration. Everything else requires custom adapters.
How does your API score?
Whether you use REST, GraphQL, or both — see exactly where your API stands across all 9 dimensions of agent readiness. Free scan, 60 seconds.