A developer platform exposes both a resource-oriented API and a graph query API. What does each do well, and what breaks?

What the resource API does well

• HTTP caching works, at the CDN, the proxy and the browser, because a GET on a URL is cacheable by infrastructure that already exists.
• Cost is predictable per endpoint, so rate limiting by request count is meaningful.
• Operationally simple: standard tooling, standard observability, obvious failure semantics.

Where it breaks: a client needing data from six resources makes six round-trips, and each endpoint returns more than any single client wants.

What the graph query API does well

• The client requests exactly the fields it needs, in one round-trip, which is a large win over slow mobile networks.
• The schema is introspectable and strongly typed, which is genuinely better developer experience.
• New client requirements frequently need no server change, since the data is already reachable.

Where it breaks:

• Caching. A POST with a query body is not cacheable by generic HTTP infrastructure, so caching must be rebuilt at the application layer with its own invalidation.
• Cost is unbounded per request. A single query can traverse deeply and fan out enormously, so rate limiting by request count is meaningless — it needs query complexity analysis and per-query cost limits.
• Observability is coarser, since every request hits one endpoint and the useful dimension is the query shape rather than the path.
• The N+1 problem moves server-side, requiring batching to avoid a resolver issuing a query per node.

The pattern that reflects reality

Both, deliberately. The graph API for first-party clients with variable needs; the resource API for integrators who want stability, cacheability and predictable limits. The cost is two surfaces to maintain, and it is usually cheaper than forcing one shape onto both audiences.