GraphQL and Flexible Query APIs Questions

Decision framework — key axes

• Client data needs

  • Dashboards: many related fields, prefer flexible, single-request joins → GraphQL.
  • Mobile: small payloads, predictable endpoints → REST or narrowly shaped GraphQL queries (persisted queries).

• Overfetching vs underfetching

  • Use GraphQL where overfetching hurts (dashboards). Use REST for simple resources to avoid complex schema queries.

• Caching

  • REST: strong HTTP/CDN caching (cache-control, ETags).
  • GraphQL: implement persisted queries, apoll o-cache/response hashing, CDN caching at persisted query level and per-field TTLs via custom cache keys.

• Schema evolution

  • GraphQL: non‑breaking changes via deprecation directives; avoid breaking removals. Maintain backwards-compatible field additions.
  • REST: versioning path/header for breaking changes.

• Analytics & observability

  • Capture field-level usage metrics, query frequency, response sizes, latency. Instrument gateway to log operation name, variables, response time. Use these to decide which queries to persist or convert to REST endpoints.

• Team skills & velocity

  • If backend teams comfortable with typed schemas and client-driven needs → GraphQL adoption cost low. If org used to REST patterns and caching, favor REST for core services.

• Client performance

  • Use persisted queries, query batching, and server-side persisted result caching for GraphQL. For mobile, enforce size/latency budgets and provide simplified REST endpoints when needed.

Recommended architecture (both workloads)

• Hybrid: GraphQL gateway (federation) above microservices + REST microservices for high-cacheable/simple resources.
• Persist frequently used dashboard queries; expose REST endpoints for mobile-critical, cacheable paths.
• Gateway handles auth, rate-limiting, analytics, and transforms persisted queries to backend calls.
• Release policy: start with GraphQL for dashboard product; introduce persisted queries and CDN caching early; convert hot mobile queries to REST if caching/size/lifecycle requires.

This balances developer DX, reduces overfetching for dashboards, preserves REST caching for mobile, and gives clear evolution and observability paths.