GraphQL Fundamentals for React Developers

REST exposes fixed-shape endpoints: GET /users/:id returns the entire user object regardless of what the client needs. GraphQL lets clients specify exactly which fields they want, eliminating over-fetching (too much data) and under-fetching (not enough data, requiring multiple requests).

One GraphQL query can retrieve a user, their posts, and each post's author in a single round-trip.

Every GraphQL API is defined by a schema written in Schema Definition Language (SDL). The schema declares types, their fields, and the root Query, Mutation, and Subscription types that clients can operate on.

The schema is the contract between the client and server. Frontend and backend teams can work in parallel once the schema is agreed upon.

A GraphQL query selects fields: { user(id: "1") { name email posts { title } } }. Nested fields traverse relationships in a single request. Aliases rename fields: { me: user(id: "1") { name } }. Fragments reuse field selections across multiple queries.

Variables make queries reusable: query GetUser($id: ID!) { user(id: $id) { name } } with variables: { id: "1" }.

Each field in the GraphQL schema has a resolver function on the server. When a client queries user.name, the user resolver fetches the user object and the name resolver (or default resolver) returns the name field.

This field-level resolution is what enables GraphQL to precisely fetch only the requested data.

If you query a list of 100 posts and each post includes its author, the naive implementation fires 100 separate database queries for authors. This N+1 problem makes GraphQL APIs slow without optimization.

DataLoader solves N+1 by batching all author lookups into a single database query using a per-request cache and batch function.

Apollo Studio and GraphQL Playground are browser-based UIs for exploring a GraphQL API interactively. They auto-complete fields from the schema, display query results, and show type documentation inline.

Using the playground is the fastest way to understand an unfamiliar GraphQL API before writing client code.

GraphQL APIs expose their own schema via an introspection query: { __schema { types { name } } }. Clients can query the schema itself to discover available types, fields, and arguments.

Code generation tools like graphql-codegen use introspection to generate TypeScript types matching the API schema automatically.

GraphQL mutations modify data: mutation CreatePost($input: PostInput!) { createPost(input: $input) { id title } }. Subscriptions establish a persistent connection (usually WebSocket) and push updates: subscription { postAdded { id title } }.

All three root types (Query, Mutation, Subscription) use the same field selection syntax.

GraphQL excels in applications with complex, nested data requirements, multiple client types (mobile, web, TV) needing different field subsets, or rapidly evolving APIs where field deprecation is preferred over endpoint versioning.

REST is simpler for CRUD APIs with predictable, flat resource shapes and excellent HTTP caching characteristics via ETags and cache headers.

Apollo Client is the most feature-rich GraphQL client: normalized cache, local state management, subscriptions, error handling links. URQL is lighter-weight with a document cache and a simpler API. React Query with graphql-request is the simplest approach for basic query+mutation without caching sophistication.

Choose based on your caching requirements: normalized cache for entities shared across queries (Apollo), simpler document cache for independent queries (URQL or React Query).

A simple SDL: type User { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: User! } type Query { user(id: ID!): User users: [User!]! }. Exclamation marks indicate non-null fields.

This schema tells the client exactly what fields exist on each type and what queries are available, enabling type-safe code generation.

What does "over-fetching" mean in the context of REST vs GraphQL?

GraphQL lets clients request exactly the fields they need (no over/under-fetching) using a schema-defined query language. Resolvers answer each field; DataLoader solves N+1. Introspection enables code generation for TypeScript types. Apollo Client, URQL, and React Query are the main React-compatible GraphQL clients.

Choose GraphQL for complex, nested, multi-client data requirements; REST for simple CRUD with predictable shapes.