Welcome to the definitive study guide for GraphQL. This document is designed to take you from a basic understanding to an intermediate/advanced level of proficiency. It focuses on conceptual clarity, architectural understanding, and practical implementation patterns using modern tools.
- Introduction to GraphQL
- Core Concepts
- Schema and Types
- Resolvers
- Queries
- Mutations
- Subscriptions
- Variables and Arguments
- Fragments
- Error Handling
- Authentication
- Performance Optimization
- Tools and Ecosystem
- Best Practices
- Common Mistakes
- Real-world Examples
- Advanced Topics (Federation & Security)
- Testing GraphQL APIs
GraphQL is an open-source data query and manipulation language for APIs, and a runtime for fulfilling those queries with your existing data. Initially developed by Facebook in 2012 and open-sourced in 2015, GraphQL provides a more efficient, powerful, and flexible alternative to the traditional REST API architecture.
At its core, GraphQL allows clients to define the structure of the data required, and exactly that structure of the data is returned from the server. This prevents the common problems of over-fetching (getting more data than you need) and under-fetching (not getting enough data and having to make subsequent requests).
Key Characteristics:
- Strongly Typed: The API is defined by a schema using the GraphQL Schema Definition Language (SDL).
- Client-Driven: The client dictates what data it needs.
- Single Endpoint: Unlike REST, which uses multiple URLs for different resources, GraphQL typically operates over a single endpoint (e.g.,
/graphql). - Protocol Agnostic: While typically served over HTTP, GraphQL is transport-layer agnostic and can be served over WebSockets, TCP, etc.
While REST (Representational State Transfer) has been the standard for API design for years, it has limitations that become apparent as applications grow in complexity, especially with the rise of mobile apps and diverse client requirements.
In REST, endpoints are tied to resources. For example:
GET /users/:idfetches a user.GET /users/:id/postsfetches the user's posts.GET /users/:id/followersfetches the user's followers.
If a client wants to display a user's profile with their posts and the names of their followers, it often requires three separate HTTP requests. This is under-fetching.
Conversely, if an endpoint GET /users/:id/fullProfile is created to solve this, but a different view only needs the user's name, that endpoint returns massive amounts of unused data. This is over-fetching.
GraphQL solves this by using a single endpoint. The client sends a specific query describing its data requirements:
query GetUserProfile {
user(id: "1") {
name
posts {
title
}
followers(limit: 3) {
name
}
}
}The server returns exactly this shape, nothing more, nothing less.
Comparison Table:
| Feature | REST | GraphQL |
|---|---|---|
| Data Fetching | Multiple endpoints per resource | Single endpoint for all data |
| Data Returned | Fixed by the server (Over/Under-fetching) | Specified by the client (Exact fetching) |
| Versioning | Often requires versioned endpoints (/v1/users) |
Versionless; fields can be deprecated seamlessly |
| Typing | Weakly typed (usually relying on OpenAPI/Swagger for docs) | Strongly typed via the GraphQL Schema |
| Tooling | Good, but fragmented | Excellent, standardized introspection allows deep IDE integration |
- Efficiency and Performance: By eliminating over-fetching and under-fetching, network payloads are minimized, which is critical for mobile networks or low-bandwidth environments.
- Rapid Product Iteration: Frontend developers can add new fields to their queries without waiting for backend developers to create or modify a REST endpoint.
- Strong Typing and Introspection: The schema serves as a contract between the client and server. Tools can introspect the schema to provide auto-completion, validation, and auto-generated documentation.
- Versionless APIs: Instead of creating a
v2API, you can add new fields and types to your schema. Old fields can be marked@deprecated, allowing clients to transition gradually.
GraphQL operations are fundamentally divided into three types. Every request sent to a GraphQL server is one of these three operations.
Queries are used to fetch data. They are analogous to GET requests in REST. Queries are read-only operations and should never modify data on the server.
Because GraphQL allows nested fields, a single query can traverse related objects and their fields, allowing you to fetch a complex graph of data in a single request.
Example conceptual query: "Get me the user with ID 1, and for that user, get their name and the titles of their last 5 posts."
Mutations are used to modify data and optionally fetch the modified data back. They are analogous to POST, PUT, PATCH, and DELETE requests in REST.
While queries are executed in parallel by the GraphQL engine to maximize speed, mutations run in series (one after another) to prevent race conditions during write operations.
Example conceptual mutation: "Create a new user with the name 'Alice', and return her newly assigned ID and creation timestamp."
Subscriptions are used to establish a long-lived connection with the server (usually via WebSockets) to receive real-time updates.
When a client subscribes to an event, the server pushes data to the client whenever that specific event occurs.
Example conceptual subscription: "Notify me with the message content and sender name whenever a new message is posted in chat room A."
The Schema is the heart of any GraphQL server. It defines what data is available, how it's structured, and what operations (Queries, Mutations, Subscriptions) the client can perform. It acts as a strict contract between the client and the server.
Schemas are written using the GraphQL Schema Definition Language (SDL).
GraphQL has a strong type system. Every field on every object must have a defined type. If a field returns an integer, the schema dictates it, and the server will enforce it.
Scalars represent the leaves of the query. They resolve to concrete data. GraphQL comes with a set of default scalar types:
Int: A signed 32-bit integer.Float: A signed double-precision floating-point value.String: A UTF-8 character sequence.Boolean:trueorfalse.ID: A unique identifier, often used to refetch an object or as the key for a cache. It serializes as a String, but it signifies that it is not intended to be human-readable.
Custom Scalars:
You can define custom scalars for specific data formats, such as Date, Email, or JSON.
scalar Date
scalar EmailAddress(Note: You will need to write custom logic in your server code to define how custom scalars are parsed and serialized).
Object types represent a group of fields. Most of the types you define in your schema will be object types.
type User {
id: ID! # The '!' means this field is non-nullable (required)
name: String!
age: Int # This field is nullable
email: String!
posts: [Post!]! # A non-nullable array of non-nullable Post objects
}
type Post {
id: ID!
title: String!
content: String
author: User!
}Type Modifiers:
String: Nullable string (can return a string or null).String!: Non-nullable string (must always return a string).[String]: Nullable array of nullable strings (can benull,[],["a", null]).[String!]: Nullable array of non-nullable strings (can benull,[],["a", "b"]).[String!]!: Non-nullable array of non-nullable strings (must be an array, elements cannot be null. e.g.,[],["a"]).
Enum types are a special kind of scalar that is restricted to a particular set of allowed values. This allows you to enforce that a field is exactly one of a few predefined options.
enum Role {
ADMIN
USER
GUEST
}
type User {
id: ID!
name: String!
role: Role!
}If a client tries to set a role to SUPERUSER, the GraphQL validation will fail before the request even reaches your business logic.
Interfaces An Interface is an abstract type that includes a certain set of fields that a type must include to implement the interface.
interface Character {
id: ID!
name: String!
friends: [Character]
}
type Human implements Character {
id: ID!
name: String!
friends: [Character]
starships: [Starship]
}
type Droid implements Character {
id: ID!
name: String!
friends: [Character]
primaryFunction: String
}Unions Union types are very similar to interfaces, but they don't get to specify any common fields between the types.
union SearchResult = Human | Droid | StarshipEvery schema must have a root Query type. This acts as the entry point into your API. Mutation and Subscription are also root types, but they are optional.
type Query {
getUser(id: ID!): User
allPosts: [Post!]!
}
type Mutation {
createUser(name: String!, email: String!): User!
}If the schema is the map, resolvers are the engines that traverse it.
A resolver is a function that is responsible for populating the data for a single field in your schema. Whenever a client requests a field, the GraphQL server invokes the resolver function associated with that field to fetch the data.
GraphQL execution is a recursive, field-by-field process. It starts at the root Query type and works its way down the graph.
Consider this query:
query {
user(id: "123") {
name
posts {
title
}
}
}The execution flow:
- The server calls the resolver for
Query.user(id: "123"). - The
Query.userresolver fetches a user object from the database (e.g.,{ id: "123", name: "Alice" }) and returns it. - The server then looks at the requested fields on
User:nameandposts. - For
User.name, it often uses a "default resolver" which just returns thenameproperty from the parent object ("Alice"). - For
User.posts, it calls the specific resolver forUser.posts.
The Resolver Signature
Every resolver function in GraphQL (in JavaScript implementations like Apollo) receives four positional arguments:
fieldName: (parent, args, context, info) => { ... }parent(orroot): The result returned by the resolver of the parent field. In step 5 above, theparentargument for theUser.postsresolver would be the{ id: "123", name: "Alice" }object returned byQuery.user.args: An object containing all the arguments provided for this field in the GraphQL query. (e.g.,{ id: "123" }).context: An object shared by all resolvers in a specific operation. This is crucial for passing state, such as authentication tokens, database connections, data loaders, or the currently logged-in user object.info: Information about the execution state of the query, including the field name, the path to the field, and the parsed AST of the query. (Advanced usage).
Resolver Implementation Example (Node.js/Apollo):
const resolvers = {
Query: {
// Resolver for Query.user
user: async (parent, args, context, info) => {
// args.id contains the ID passed in the query
return await context.db.users.findById(args.id);
},
allPosts: async (parent, args, context) => {
return await context.db.posts.findAll();
}
},
User: {
// Resolver for the 'posts' field on the 'User' type
// We only need to define this if the data isn't naturally returned
// by the Query.user resolver.
posts: async (parent, args, context) => {
// 'parent' is the user object resolved by Query.user
return await context.db.posts.findByAuthorId(parent.id);
}
}
};The Power of Default Resolvers:
Notice we didn't write a resolver for User.name. If a resolver is not defined, GraphQL assumes the parent object has a property with the exact same name as the field and returns it automatically. This saves massive amounts of boilerplate code.
Queries are the primary mechanism for retrieving data. They are defined on the client side and validated against the schema on the server.
A basic query asks for specific fields on a specific root query field.
Client Request:
query GetBook {
book(id: "1") {
title
author
publishDate
}
}Server Response (JSON):
{
"data": {
"book": {
"title": "Dune",
"author": "Frank Herbert",
"publishDate": "1965-08-01"
}
}
}Notice how the shape of the response exactly matches the shape of the query.
GraphQL's true power lies in its ability to traverse relationships seamlessly.
Schema:
type Author {
id: ID!
name: String!
books: [Book!]!
}
type Book {
title: String!
publishedYear: Int!
author: Author!
}Client Request:
query GetAuthorAndTheirBooks {
author(id: "42") {
name
books {
title
publishedYear
}
}
}This single query fetches the author, and then traverses the relationship to fetch all books by that author, extracting specific fields from both entity types. In REST, this would typically require multiple requests or a heavily customized aggregate endpoint.
Aliases: If you need to query the same field multiple times with different arguments in a single request, you must use aliases to prevent naming conflicts in the JSON response.
query CompareUsers {
admin: user(id: "1") {
name
}
guest: user(id: "2") {
name
}
}Response:
{
"data": {
"admin": { "name": "Alice" },
"guest": { "name": "Bob" }
}
}Mutations modify data and return a payload. It is a best practice for mutations to return the object that was modified, allowing the client to update its UI or local cache immediately without a subsequent fetch.
Schema Definition:
input UserInput {
name: String!
email: String!
age: Int
}
type Mutation {
createUser(input: UserInput!): User!
updateUser(id: ID!, age: Int!): User!
deleteUser(id: ID!): Boolean!
}(Note the use of input types. Input types are special object types specifically designed to be passed as arguments. You cannot use a regular type as an argument).
Client Request (Creation):
mutation CreateNewUser {
createUser(input: { name: "Charlie", email: "charlie@example.com" }) {
id # Ask for the newly generated ID
name
email
}
}Resolver Implementation:
const resolvers = {
Mutation: {
createUser: async (_, { input }, context) => {
// 1. Validate input (optional, depending on setup)
// 2. Perform database operation
const newUser = await context.db.users.create({
name: input.name,
email: input.email,
age: input.age
});
// 3. Return the created object
return newUser;
}
}
};Why return the modified object?
In modern frontend applications using tools like Apollo Client or Relay, the client maintains a normalized cache of the graph. If a mutation returns the updated object with its id, the client's cache automatically updates the corresponding entity, and any UI components observing that entity instantly re-render with the new data.
Subscriptions maintain an active connection (usually WebSockets) to the GraphQL server. The server pushes updates to the client whenever a predefined event occurs.
- Define in Schema:
type Subscription {
postCreated: Post!
}- Client Subscribes:
subscription OnPostCreated {
postCreated {
id
title
author {
name
}
}
}The client sends this operation and keeps the connection open.
-
Server Resolves: Subscription resolvers are different. Instead of returning data directly, they return an
AsyncIteratorthat listens to an event publisher (like Redis PubSub, Kafka, or Node's EventEmitter). -
Publishing Events: When a mutation occurs (e.g.,
createPost), the mutation resolver publishes an event. The subscription machinery catches this event, executes the requested fields (id,title,author.name), and pushes the payload over the WebSocket to all subscribed clients.
Subscriptions are complex to scale because they require managing stateful, long-lived connections, but they are essential for real-time features like chat, live scores, or collaborative editing.
Hardcoding arguments directly into query strings is a bad practice. It prevents query caching, makes queries hard to construct dynamically, and opens the door to injection attacks. GraphQL provides first-class support for variables.
Variables allow you to write a static query structure and pass dynamic values at runtime.
Client Request Structure:
A GraphQL request payload is typically a JSON object containing query and optionally variables.
{
"query": "query GetUser($userId: ID!) { user(id: $userId) { name } }",
"variables": {
"userId": "123"
}
}Query Syntax:
# 1. Declare the variable and its type in the operation definition
query GetUser($userId: ID!) {
# 2. Use the variable as an argument
user(id: $userId) {
name
email
}
}Benefits of Variables:
- Security: Prevents malicious injection since variables are parsed separately from the query string.
- Performance: Clients can pre-compile queries or servers can cache parsed query ASTs since the query string remains constant.
- Maintainability: Easier to read and debug.
Default Variables: You can provide default values for variables in the query definition.
query GetPosts($limit: Int = 10) {
posts(limit: $limit) {
title
}
}Fragments are the primary unit of composition in GraphQL. They allow you to define a set of fields on a specific type and reuse them across multiple queries or mutations.
- DRY (Don't Repeat Yourself): If you fetch the same fields for a
Userin 5 different queries, writing them out 5 times is tedious and prone to errors if the requirements change. - Component Colocation (UI Integration): In frameworks like React, you can define a fragment alongside the UI component that requires that data. The parent component then gathers all child fragments into one massive query. This ensures a component always gets exactly the data it needs to render.
Definition:
fragment UserProfile on User {
id
name
avatarUrl
bio
}Usage:
query GetDashboardData {
currentUser {
...UserProfile
email # Additional fields specific to this query
}
suggestedFriends {
...UserProfile
}
}Inline fragments are used when querying a field that returns an Interface or a Union type, allowing you to ask for specific fields depending on the concrete type returned.
# Schema
union SearchResult = User | Post
# Query
query Search($term: String!) {
search(text: $term) {
... on User {
id
name
role
}
... on Post {
id
title
content
}
}
}If a result is a User, the response includes name and role. If it's a Post, it includes title and content.
Unlike REST, which heavily relies on HTTP status codes (404, 500, etc.) to indicate success or failure, GraphQL almost always returns an HTTP 200 OK status, even if the query completely failed.
A GraphQL response is a map that contains a data key, an errors key, or both.
Successful Response:
{
"data": {
"user": { "name": "Alice" }
}
}Failed Response (e.g., Validation Error):
{
"errors": [
{
"message": "Cannot query field 'password' on type 'User'.",
"locations": [{ "line": 3, "column": 5 }]
}
]
}Partial Success: If a query asks for a user's name and their posts, but the database connection for posts fails, the server can return partial data alongside the error.
{
"data": {
"user": {
"name": "Alice",
"posts": null
}
},
"errors": [
{
"message": "Failed to fetch posts due to database timeout.",
"path": ["user", "posts"]
}
]
}In production, you should not expose raw stack traces or internal database errors to the client. Modern GraphQL servers (like Apollo) allow you to format errors before they are sent.
You can throw specific error classes (e.g., AuthenticationError, UserInputError) in your resolvers, which map to specific error codes in the response extensions.
// Resolver example
user: async (_, args, context) => {
if (!context.user) {
throw new AuthenticationError('You must be logged in');
}
const user = await db.findById(args.id);
if (!user) {
throw new UserInputError('User not found', { invalidArgs: ['id'] });
}
return user;
}Authentication (who you are) and Authorization (what you can do) are critical. GraphQL doesn't dictate how you implement these; it's transport agnostic.
The standard pattern for authentication in GraphQL is to process tokens (like JWTs) at the HTTP middleware layer, determine the user, and place that user object onto the GraphQL context.
Express + Apollo Setup:
const server = new ApolloServer({
typeDefs,
resolvers,
// Context function runs before every request
context: async ({ req }) => {
const token = req.headers.authorization || '';
// Try to retrieve a user with the token
const user = await getUserFromToken(token);
// Add the user to the context
return { user };
},
});Once the user is in the context, resolvers can access it to enforce authorization rules.
const resolvers = {
Mutation: {
deletePost: async (_, { id }, context) => {
// 1. Authentication Check
if (!context.user) {
throw new AuthenticationError("Must log in.");
}
const post = await db.posts.findById(id);
// 2. Authorization Check (Only author or admin can delete)
if (post.authorId !== context.user.id && context.user.role !== 'ADMIN') {
throw new ForbiddenError("Not authorized to delete this post.");
}
await db.posts.delete(id);
return true;
}
}
}(For complex applications, authorization logic should be moved out of resolvers and into dedicated business logic layers or directives to keep resolvers clean).
Because clients can request arbitrary graph structures, GraphQL APIs are uniquely vulnerable to performance bottlenecks if not carefully implemented.
The N+1 problem is the most infamous performance issue in GraphQL. It occurs because resolvers execute independently for each item in a list.
The Scenario: Consider querying a list of 10 users and their associated company.
query {
users(limit: 10) {
name
company {
name
}
}
}The Flawed Execution Flow:
Query.usersresolver runs. Executes 1 SQL query:SELECT * FROM users LIMIT 10;. Returns an array of 10 user objects.- The GraphQL engine iterates over the 10 users. For each user, it calls the
User.companyresolver. - The
User.companyresolver executes a SQL query:SELECT * FROM companies WHERE id = ?. - Result: 1 query for users + 10 queries for companies = 11 total database queries.
If you requested 100 users, it would execute 101 queries. This destroys database performance.
DataLoader is a utility (originally built by Facebook) designed specifically to solve the N+1 problem through batching and caching on a per-request basis.
Instead of hitting the database immediately in the resolver, you pass the ID to a DataLoader. The DataLoader waits a tick (using process.nextTick or similar microtask queues) to collect all IDs requested across the entire graph. It then executes a single bulk query.
Implementation with DataLoader:
- Define the Loader:
const DataLoader = require('dataloader');
// The batch function receives an array of keys (e.g., [1, 2, 3, ...])
const batchGetCompanies = async (companyIds) => {
// Execute ONE query: SELECT * FROM companies WHERE id IN (1, 2, 3)
const companies = await db.companies.find({ id: { $in: companyIds } });
// DataLoader requires the returned array to be the exact same length
// and order as the incoming companyIds array.
return companyIds.map(id => companies.find(c => c.id === id) || null);
};
// Create a new loader instance PER REQUEST (put it in context)
const companyLoader = new DataLoader(batchGetCompanies);- Use in Resolver:
const resolvers = {
User: {
company: async (parent, args, context) => {
// Instead of db.companies.findById(parent.companyId)
return context.companyLoader.load(parent.companyId);
}
}
}Now, the execution flow for 10 users is:
Query.users-> 1 query.User.companycalled 10 times. Each pushes an ID to the loader.- Loader batches them and fires 1 query (
WHERE id IN (...)). - Total queries: 2. (Down from 11).
Caching in GraphQL is notoriously harder than in REST because the endpoint is always POST /graphql. You cannot rely on standard HTTP GET caching mechanisms (like CDNs or Varnish) easily.
Strategies:
- Persisted Queries (APQ): The client hashes the query string and sends the hash. If the server recognizes the hash, it executes the query. If not, the client sends the full query. Because hashes are short, they can be sent via
GET /graphql?hash=123, allowing CDN caching. - Whole-Query Caching (Redis): Cache the entire JSON response based on the query string and variables. Complex to invalidate.
- Data-Level Caching: Cache the underlying entities (e.g., caching the user object in Redis inside the
findByIdfunction). The DataLoader provides a per-request cache automatically, but a distributed cache across requests helps significantly.
GraphQL has a massive ecosystem. You rarely build a GraphQL server from scratch.
- Apollo Server (Node.js): The industry standard. Highly extensible, supports plugins, federated graphs, and great performance.
- GraphQL.js: The reference implementation of the spec in JavaScript.
- Hasura / PostGraphile: Tools that automatically generate a fully-featured GraphQL API directly from your PostgreSQL database schema.
- Prisma: A modern ORM that pairs exceptionally well with GraphQL resolvers, providing type-safe database access.
- GraphQL Yoga: A modern, lightweight server alternative by The Guild.
- Apollo Client (React/Vue/Angular/iOS/Android): A powerful state management library. It automatically normalizes graph data, caches it locally, manages loading/error states, and updates UI components dynamically.
- Relay (React): Built by Facebook. Incredibly highly optimized for performance and component-driven data fetching. Steeper learning curve than Apollo.
- urql: A highly customizable and versatile GraphQL client by Formidable.
- GraphQL Request: A minimalist client for simple scripts or environments where caching isn't needed.
To build scalable, maintainable GraphQL APIs, adhere to these guidelines.
- Design for the Client, not the Database: The schema should reflect how the UI consumes data, not how your SQL tables are structured. Hide implementation details.
- Use Specific Mutations: Avoid generic
updateUsermutations that take a massive payload of all possible fields. Instead, use domain-specific mutations likechangeUserPassword,updateUserAvatar,suspendAccount. This makes intent clear and validation easier. - Naming Conventions:
- Types:
PascalCase(User,BlogPost). - Fields:
camelCase(firstName,createdAt). - Enums:
ALL_CAPS(ACTIVE,PENDING).
- Types:
- Pagination: Do not return massive arrays. Use pagination patterns. The Relay Cursor Connections specification is the industry standard for pagination in GraphQL, utilizing
edges,node,cursor, andpageInfo. - Versionless Evolution: Never create
v2. Instead, add new fields and mark old ones with the@deprecated(reason: "Use newField instead")directive. Monitor field usage to determine when it is safe to remove the deprecated fields.
- Thin Resolvers: Resolvers should NOT contain complex business logic. A resolver's only job is to extract arguments, call a dedicated controller/service layer function, and return the result.
Bad: Writing raw SQL inside a resolver.
Good:
return context.services.user.processPayment(args.amount) - Use Custom Scalars: Use custom scalars for types like
DateTime,URL, orUUIDto enforce validation at the schema level rather than in every resolver. - Generate Types: Use tools like GraphQL Code Generator to automatically generate TypeScript types from your schema. This ensures your resolvers and client code are perfectly in sync with the graph.
- Ignoring the N+1 Problem: Deploying a server to production without DataLoaders. It will fail under load.
- Exposing the Entire Database: Tools like Hasura are great for prototyping, but directly exposing your entire database schema to the client frontend often leads to tight coupling and security risks. Wrap auto-generated APIs in a business logic layer if complexity requires it.
- Deep Nesting without Limits: A malicious client could write a deeply nested query to crash your server:
Fix: Implement query depth limiting and query complexity analysis using tools like
query { author { books { author { books { author { name } } } } } }
graphql-depth-limit. - Forgetting Input Validation: Just because the schema guarantees a variable is an
Intdoesn't mean it's a valid ID. Always validate business logic rules (e.g.,age > 18,email format is valid) in your service layer.
Let's look at a complete, self-contained, conceptual example of a simple Task Management API to tie everything together.
scalar DateTime
enum TaskStatus {
TODO
IN_PROGRESS
DONE
}
type User {
id: ID!
username: String!
tasks(status: TaskStatus): [Task!]!
}
type Task {
id: ID!
title: String!
description: String
status: TaskStatus!
createdAt: DateTime!
assignee: User
}
type Query {
me: User
task(id: ID!): Task
}
input CreateTaskInput {
title: String!
description: String
assigneeId: ID
}
type Mutation {
createTask(input: CreateTaskInput!): Task!
updateTaskStatus(id: ID!, status: TaskStatus!): Task!
}const { GraphQLScalarType } = require('graphql');
// Mock Database Service
const db = {
users: [{ id: "1", username: "developer_dan" }],
tasks: [
{ id: "100", title: "Learn GraphQL", status: "TODO", createdAt: new Date(), assigneeId: "1" }
]
};
const resolvers = {
// Custom Scalar Implementation
DateTime: new GraphQLScalarType({
name: 'DateTime',
description: 'A valid Date object',
serialize(value) { return value.toISOString(); },
}),
Query: {
me: (parent, args, context) => {
// Assuming context contains the authenticated user
if (!context.userId) return null;
return db.users.find(u => u.id === context.userId);
},
task: (_, { id }) => {
return db.tasks.find(t => t.id === id);
}
},
Mutation: {
createTask: (_, { input }) => {
const newTask = {
id: String(Math.random()), // In real app, use UUID or DB auto-increment
title: input.title,
description: input.description,
status: "TODO",
createdAt: new Date(),
assigneeId: input.assigneeId
};
db.tasks.push(newTask);
return newTask;
},
updateTaskStatus: (_, { id, status }) => {
const taskIndex = db.tasks.findIndex(t => t.id === id);
if (taskIndex === -1) throw new Error("Task not found");
db.tasks[taskIndex].status = status;
return db.tasks[taskIndex];
}
},
// Field Resolvers to handle relationships
User: {
tasks: (parent, args) => {
let userTasks = db.tasks.filter(t => t.assigneeId === parent.id);
if (args.status) {
userTasks = userTasks.filter(t => t.status === args.status);
}
return userTasks;
}
},
Task: {
assignee: (parent) => {
if (!parent.assigneeId) return null;
// In production, use a DataLoader here!
return db.users.find(u => u.id === parent.assigneeId);
}
}
};1. Fetching the Dashboard (Query)
query GetMyDashboard {
me {
username
tasks(status: TODO) {
id
title
createdAt
}
}
}2. Creating a Task (Mutation)
mutation AddNewTask($input: CreateTaskInput!) {
createTask(input: $input) {
id
title
status
}
}Variables Payload:
{
"input": {
"title": "Write Unit Tests",
"assigneeId": "1"
}
}As organizations grow, maintaining a single, monolithic GraphQL server becomes an architectural bottleneck. Multiple teams working on the same schema leads to deployment conflicts and tight coupling.
What is Federation? Apollo Federation allows you to divide your graph into multiple, smaller GraphQL services (called subgraphs), which are then composed into a single, unified "supergraph" by a Gateway.
How it works:
- Users Subgraph: Handles queries related to users.
- Products Subgraph: Handles queries related to products.
- Reviews Subgraph: Handles reviews, tying users to products.
The Gateway routes incoming requests to the appropriate subgraphs, merges the responses, and returns them to the client. The client is completely unaware that multiple microservices are powering the graph.
Because a single GraphQL query can request an arbitrary amount of data, traditional rate limiting (e.g., 100 requests per minute) is insufficient. One massive query can take down the server.
Solutions:
- Query Cost Analysis: Assign a "cost" or "weight" to each field in the schema. Before executing the query, the server calculates the total cost. If it exceeds a threshold (e.g., 1000 points), the query is rejected.
- Depth Limiting: Prevent queries from nesting deeper than a specified limit (e.g., maximum depth of 5).
- Amount Limiting: For fields that return lists, require pagination arguments (
first,last) and enforce hard maximums (e.g.,firstcannot exceed 100).
Testing GraphQL is generally more straightforward than REST because of the strong schema and typed nature of the language.
Ensure your schema compiles and contains no syntax errors. Tools like graphql-schema-linter can enforce naming conventions and deprecation rules.
Resolvers are just functions. You can test them in isolation by passing mock parent, args, and context objects.
// Example Jest test
test('User.tasks resolver fetches tasks for user', async () => {
const mockContext = { db: { tasks: { findByAssignee: jest.fn().mockResolvedValue([{ id: 1 }]) } } };
const parent = { id: 'user-1' };
const result = await resolvers.User.tasks(parent, {}, mockContext);
expect(mockContext.db.tasks.findByAssignee).toHaveBeenCalledWith('user-1');
expect(result).toHaveLength(1);
});Using tools like apollo-server-testing (or simply sending HTTP POST requests to your test server instance), you can execute full GraphQL operations against an in-memory database to verify the entire request lifecycle.
const { createTestClient } = require('apollo-server-testing');
const server = new ApolloServer({ typeDefs, resolvers, context: () => ({ user: { id: 1 } }) });
const { query } = createTestClient(server);
test('Fetches current user dashboard', async () => {
const GET_ME = gql`query { me { id } }`;
const res = await query({ query: GET_ME });
expect(res.data.me.id).toBe('1');
});This concludes the comprehensive guide to GraphQL. By mastering these core concepts, schemas, resolvers, optimization techniques, and advanced patterns, you are well-equipped to design, build, and maintain highly efficient and scalable API infrastructures.