GraphQL

GraphQL is a query language and runtime for APIs — clients describe exactly what data they need in a query, and the server returns precisely that shape. REST uses predefined endpoints that return fixed data shapes regardless of what the client actually needs. Key differences: (1) Over/under-fetching — GraphQL returns exactly what's requested; REST returns the endpoint's fixed shape. (2) Multiple resources — one GraphQL query can fetch a user, their orders, and order items; REST requires 3 separate requests. (3) Type system — GraphQL has a strongly-typed schema; REST has no enforced contract. (4) Versioning — GraphQL evolves via schema deprecation; REST versions via URL (/v1, /v2). 70% of organizations now use GraphQL in production, confirming it's not a niche choice.

Use GraphQL when: (1) multiple different clients (web, mobile, third-party) consume the same API with different data needs; (2) you have complex nested data relationships that require multiple REST round-trips to assemble; (3) you're building a microservice architecture that needs a unified API surface; (4) you want real-time subscriptions alongside request-response queries in the same system; (5) you're building a developer-facing API where introspection and self-documentation matter. Stick with REST for: simple CRUD APIs with a single client, file upload-heavy APIs, highly cacheable public APIs where CDN caching is critical, or teams without GraphQL schema design experience.

The September 2025 edition of the GraphQL specification is current, announced at GraphQLConf 2025 (October 2025). A pre-release Working Draft dated April 2, 2026 represents the next iteration in progress. The specification is maintained by the GraphQL Foundation (a Linux Foundation project) with contributions from Meta, Apollo, The Guild, Shopify, and other major users. The September 2025 spec introduced incremental delivery improvements and clarifications to stream and defer directives. The reference implementation graphql-js tracks the specification closely and has 33.6 million weekly npm downloads.

Apollo Federation v2 is an architecture for composing multiple GraphQL subgraphs (owned by different teams) into a single supergraph. An Apollo Router sits in front of all subgraphs and routes queries to the appropriate services, stitching results together. You need Federation when: multiple teams own different parts of your API, you have microservices that need to expose a unified GraphQL surface, or your schema has grown too large for a single team to maintain. You don't need Federation for: single-team APIs, monolithic backends, or APIs with fewer than 3–4 distinct data ownership boundaries.

Hasura is a GraphQL engine that generates a complete GraphQL API from your PostgreSQL (or other supported) database schema automatically — queries, mutations, subscriptions, and relationship traversal derived from foreign keys, all without writing custom resolvers. It ships in minutes: point Hasura at your database, configure permissions, and you have a production-ready API. Add custom business logic via Hasura Actions (REST webhooks) and Event Triggers (CDC on table writes). Hasura's permission system (row-level and column-level) maps to JWT claims for multi-tenant security. It's the right choice when your data model is the API and you want to eliminate the resolver layer entirely.

Authentication in GraphQL follows the same patterns as REST — JWT tokens or session cookies in HTTP headers, validated in middleware before reaching resolvers. Authorization is more nuanced: (1) Schema-level — use directives (@auth, @hasRole) to protect entire types or fields. (2) Resolver-level — check permissions inside each resolver before fetching data. (3) Database-level — use Row Level Security (PostgreSQL + Hasura) to enforce access at the data layer. The most robust pattern is database-level authorization via RLS — even a buggy resolver cannot return data the user isn't authorized to see. We implement field-level authorization for sensitive fields (payment details, PII) separate from the top-level auth check.

The N+1 problem: a GraphQL query for a list of 100 orders, each with their customer, triggers 1 query for orders + 100 individual customer queries = 101 queries total. This happens because resolvers execute independently and don't know about sibling resolver executions. The solution is DataLoader — a utility that batches all child entity lookups within a single JavaScript event loop tick into one database query. The 100 individual customer lookups become 1 query: SELECT * FROM customers WHERE id IN (...100 ids). We implement DataLoader as standard practice in all GraphQL services — it's not optional for production APIs with relationship data.

GraphQL Subscriptions establish a WebSocket connection and push updates to clients when specified events occur. The subscription query defines exactly which fields to receive on each update — the same syntax as standard queries. Server implementations: Apollo Server uses graphql-ws (WebSocket protocol); Hasura uses PostgreSQL's LISTEN/NOTIFY to stream database changes as subscription events. Apollo Client on the frontend manages subscription lifecycle — connection, reconnection, and merging new data into the client cache. Common use cases: live order status, real-time auction bids, collaborative editing notifications, dashboard metric updates.

Our standard GraphQL stack: Apollo Server 5 for Node.js backends (with Federation v2 for microservices); Hasura for instant PostgreSQL-backed APIs; The Guild's graphql-yoga as a lightweight alternative to Apollo Server; graphql-codegen for TypeScript type generation from schema; DataLoader for N+1 batching; graphql-query-complexity for query cost analysis and DOS protection; Apollo Client for React/Next.js frontends; Strawberry for Python backends; and Apollo Studio for schema registry and production monitoring. We select the right combination based on your team's language, scale requirements, and whether you need Federation.

GraphQL security requires several layers: (1) Query complexity limits — assign cost weights to fields and reject queries exceeding a threshold; prevents 'query bombs' that trigger exponential resolver chains. (2) Depth limiting — reject queries nested beyond a maximum depth (typically 5–7 levels). (3) Rate limiting — limit requests per IP or per authenticated user per time window. (4) Introspection in production — disable schema introspection for public production APIs to avoid exposing the full schema to attackers (allow it for developer-facing APIs). (5) Persisted queries — for internal APIs, whitelist approved query hashes and reject arbitrary queries entirely. (6) Field-level authorization — never rely solely on query structure to protect sensitive fields; authorize each field in its resolver or via RLS.