GraphQL is a query language for APIs that gives clients the power to request exactly the data they need. No more over-fetching or under-fetching data from REST endpoints.

What is GraphQL?

Created by Facebook in 2012, GraphQL is a specification for APIs that allows clients to define the structure of the data they need. The server returns only what’s requested.

Key Differences from REST:

• Single endpoint vs multiple endpoints
• Client-specified queries vs fixed responses
• Strong typing with schema definition
• No over/under-fetching of data

Why Choose GraphQL?

Advantages:

• Fetch multiple resources in a single request
• No versioning required - schema evolves
• Excellent developer experience with introspection
• Real-time updates with subscriptions
• Auto-generated documentation

When to Use REST vs GraphQL:

• REST: Simple CRUD, caching priority, public APIs
• GraphQL: Complex data requirements, mobile apps, rapid iteration

Schema Definition

GraphQL uses a strongly-typed schema:

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  createdAt: DateTime!
}

type Query {
  user(id: ID!): User
  users: [User!]!
  post(id: ID!): Post
}

type Mutation {
  createUser(name: String!, email: String!): User!
  updatePost(id: ID!, title: String, content: String): Post!
  deletePost(id: ID!): Boolean!
}

Type Modifiers:

• String - nullable string
• String! - required string
• [String] - array of nullable strings
• [String!]! - required array of required strings

Queries

Fetch exactly what you need:

# Basic query
query {
  user(id: "123") {
    name
    email
  }
}

# Nested query
query {
  user(id: "123") {
    name
    posts {
      title
      createdAt
    }
  }
}

# Multiple queries
query {
  user1: user(id: "123") {
    name
  }
  user2: user(id: "456") {
    name
  }
}

# With variables
query GetUser($userId: ID!) {
  user(id: $userId) {
    name
    email
    posts {
      title
    }
  }
}

Mutations

Modify data on the server:

mutation {
  createUser(name: "John Doe", email: "john@example.com") {
    id
    name
    email
  }
}

mutation UpdatePost($id: ID!, $title: String!) {
  updatePost(id: $id, title: $title) {
    id
    title
    updatedAt
  }
}

Setting Up a GraphQL Server (Node.js)

Install dependencies:

npm install apollo-server graphql

Create server:

const { ApolloServer, gql } = require('apollo-server');

// Schema
const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
  }

  type Query {
    users: [User!]!
    user(id: ID!): User
  }

  type Mutation {
    createUser(name: String!, email: String!): User!
  }
`;

// In-memory data
let users = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' }
];

// Resolvers
const resolvers = {
  Query: {
    users: () => users,
    user: (_, { id }) => users.find(u => u.id === id)
  },
  Mutation: {
    createUser: (_, { name, email }) => {
      const user = {
        id: String(users.length + 1),
        name,
        email
      };
      users.push(user);
      return user;
    }
  }
};

const server = new ApolloServer({ typeDefs, resolvers });

server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);
});

Client-Side Usage

Using fetch:

async function fetchUser(userId) {
  const query = `
    query GetUser($id: ID!) {
      user(id: $id) {
        name
        email
      }
    }
  `;

  const response = await fetch('http://localhost:4000/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query,
      variables: { id: userId }
    })
  });

  const { data } = await response.json();
  return data.user;
}

Using Apollo Client (React):

import { ApolloClient, InMemoryCache, gql, useQuery } from '@apollo/client';

const client = new ApolloClient({
  uri: 'http://localhost:4000/graphql',
  cache: new InMemoryCache()
});

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      email
      posts {
        title
      }
    }
  }
`;

function UserProfile({ userId }) {
  const { loading, error, data } = useQuery(GET_USER, {
    variables: { id: userId }
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      <h1>{data.user.name}</h1>
      <p>{data.user.email}</p>
      <ul>
        {data.user.posts.map(post => (
          <li key={post.title}>{post.title}</li>
        ))}
      </ul>
    </div>
  );
}

Subscriptions for Real-Time Data

type Subscription {
  postAdded: Post!
}

Server implementation:

const { PubSub } = require('graphql-subscriptions');
const pubsub = new PubSub();

const resolvers = {
  Subscription: {
    postAdded: {
      subscribe: () => pubsub.asyncIterator(['POST_ADDED'])
    }
  },
  Mutation: {
    createPost: (_, { title, content }) => {
      const post = { id: '...', title, content };
      pubsub.publish('POST_ADDED', { postAdded: post });
      return post;
    }
  }
};

Best Practices

1. Design schema first - Define types before implementation
2. Use DataLoader to prevent N+1 query problems
3. Implement pagination for large lists
4. Add authentication at resolver level
5. Handle errors with proper error types
6. Monitor performance with Apollo Studio or similar tools

Common Pitfalls

• Over-nesting queries (performance impact)
• Not implementing rate limiting
• Exposing entire database schema
• Ignoring caching strategies
• Not validating input properly

Tools and Resources

• Apollo Server - Popular GraphQL server
• GraphQL Playground - Interactive query IDE
• Postman - Now supports GraphQL
• GraphQL Code Generator - Auto-generate TypeScript types
• graphql.org - Official documentation

GraphQL offers powerful flexibility for modern applications. Start with simple queries, understand the type system, and gradually adopt advanced features like subscriptions and federation.