GraphQL Schema Design

Also Known As

TL;DR

Explanation

GraphQL schema design best practices: make nullable the default (required only when absence is an error), use connection types for lists (enables pagination metadata), prefix mutations with the action (createUser, updateUser, deleteUser), use input types for mutation arguments, never return raw IDs without the entity, and solve N+1 with DataLoader batching. Versioning: GraphQL schemas evolve by adding nullable fields and deprecating old ones — never removing fields without a sunset period.

Common Misconception

Why It Matters

Common Mistakes

• No DataLoader — each resolver fetches its own data; a query for 100 users with their posts fires 101 queries.
• Non-null fields that should be nullable — a single null value errors the entire query instead of just that field.
• Mutations that return Boolean instead of the mutated type — clients cannot get updated data without a separate query.
• Deeply nested mutations — GraphQL mutations should be flat; nesting creates complex error handling.

Code Examples

// N+1 without DataLoader:
type Query { users: [User!]! }
type User { posts: [Post!]! }  // Each user resolver fires a separate DB query
// 100 users → 1 (users) + 100 (posts) = 101 queries

// DataLoader batches resolver calls:
$postLoader = new DataLoader(function(array $userIds): array {
    $posts = Post::whereIn('user_id', $userIds)->get()->groupBy('user_id');
    return array_map(fn($id) => $posts[$id] ?? [], $userIds);
});

// Resolver:
'posts' => fn(User $user) => $postLoader->load($user->id),
// 100 users → 1 (users) + 1 (posts batch) = 2 queries

References

• ↗ https://graphql.org/learn/best-practices/

Tags

Related Terms