GraphQL with Apollo Server: A Practical Introduction Beyond REST

mkdir graphql-bookstore && cd graphql-bookstore
npm init -y
npm pkg set type=module   # ES modules, so top-level await works
npm install @apollo/server graphql
npm install -D typescript @types/node tsx
npx tsc --init --types node

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';

// Type definitions describe the shape of your data
const typeDefs = `#graphql
  type Book {
    id: ID!
    title: String!
    author: Author!
    genre: String!
    publishedYear: Int
    rating: Float
  }

  type Author {
    id: ID!
    name: String!
    bio: String
    books: [Book!]!
  }

  type Query {
    books: [Book!]!
    book(id: ID!): Book
    authors: [Author!]!
    author(id: ID!): Author
  }
`;

// Sample data (in production, this would be a database)
const authors = [
  { id: '1', name: 'Chimamanda Adichie', bio: 'Nigerian novelist and essayist' },
  { id: '2', name: 'Haruki Murakami', bio: 'Japanese author of surrealist fiction' },
];

const books = [
  { id: '1', title: 'Half of a Yellow Sun', authorId: '1', genre: 'Historical Fiction', publishedYear: 2006, rating: 4.3 },
  { id: '2', title: 'Norwegian Wood', authorId: '2', genre: 'Literary Fiction', publishedYear: 1987, rating: 4.0 },
  { id: '3', title: 'Americanah', authorId: '1', genre: 'Contemporary Fiction', publishedYear: 2013, rating: 4.5 },
];

// Resolvers define how to fetch the data for each field
const resolvers = {
  Query: {
    books: () => books,
    book: (_: unknown, { id }: { id: string }) => books.find(b => b.id === id),
    authors: () => authors,
    author: (_: unknown, { id }: { id: string }) => authors.find(a => a.id === id),
  },
  Book: {
    author: (book: { authorId: string }) => authors.find(a => a.id === book.authorId),
  },
  Author: {
    books: (author: { id: string }) => books.filter(b => b.authorId === author.id),
  },
};

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

// Top-level await works because package.json has "type": "module"
const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});

console.log(`Server ready at ${url}`);

query {
  books {
    title
    rating
    author {
      name
    }
  }
}

// One merged schema: base types plus inputs, enum and mutations
export const typeDefs = `#graphql
  type Book {
    id: ID!
    title: String!
    author: Author!
    genre: String!
    publishedYear: Int
    rating: Float
  }

  type Author {
    id: ID!
    name: String!
    bio: String
    books: [Book!]!
  }

  input CreateBookInput {
    title: String!
    authorId: ID!
    genre: String!
    publishedYear: Int
    rating: Float
  }

  input UpdateBookInput {
    title: String
    genre: String
    publishedYear: Int
    rating: Float
  }

  type DeleteResponse {
    success: Boolean!
    message: String!
  }

  enum SortOrder {
    ASC
    DESC
  }

  type Query {
    books(genre: String, sortBy: SortOrder): [Book!]!
    book(id: ID!): Book
    searchBooks(term: String!): [Book!]!
    authors: [Author!]!
    author(id: ID!): Author
  }

  type Mutation {
    createBook(input: CreateBookInput!): Book!
    updateBook(id: ID!, input: UpdateBookInput!): Book
    deleteBook(id: ID!): DeleteResponse!
  }
`;

export interface Author {
  id: string;
  name: string;
  bio?: string;
}

export interface Book {
  id: string;
  title: string;
  authorId: string;
  genre: string;
  publishedYear?: number | null;
  rating?: number | null;
}

// In-memory sample data (swap for a database later)
export const authors: Author[] = [
  { id: '1', name: 'Chimamanda Adichie', bio: 'Nigerian novelist and essayist' },
  { id: '2', name: 'Haruki Murakami', bio: 'Japanese author of surrealist fiction' },
];

export const books: Book[] = [
  { id: '1', title: 'Half of a Yellow Sun', authorId: '1', genre: 'Historical Fiction', publishedYear: 2006, rating: 4.3 },
  { id: '2', title: 'Norwegian Wood', authorId: '2', genre: 'Literary Fiction', publishedYear: 1987, rating: 4.0 },
  { id: '3', title: 'Americanah', authorId: '1', genre: 'Contemporary Fiction', publishedYear: 2013, rating: 4.5 },
];

let nextId = books.length + 1;
export const generateId = (): string => String(nextId++);

import { GraphQLError } from 'graphql';
import { books, authors, generateId, type Book, type Author } from './data.js';

// Argument types mirror the schema (GraphQL Code Generator can produce these)
type SortOrder = 'ASC' | 'DESC';

interface CreateBookInput {
  title: string;
  authorId: string;
  genre: string;
  publishedYear?: number | null;
  rating?: number | null;
}

interface UpdateBookInput {
  title?: string | null;
  genre?: string | null;
  publishedYear?: number | null;
  rating?: number | null;
}

export const resolvers = {
  Query: {
    books: (_: unknown, { genre, sortBy }: { genre?: string | null; sortBy?: SortOrder | null }) => {
      let result = genre
        ? books.filter(b => b.genre === genre)
        : [...books];

      if (sortBy === 'ASC') {
        result.sort((a, b) => a.title.localeCompare(b.title));
      } else if (sortBy === 'DESC') {
        result.sort((a, b) => b.title.localeCompare(a.title));
      }

      return result;
    },

    book: (_: unknown, { id }: { id: string }) => {
      const book = books.find(b => b.id === id);
      if (!book) {
        throw new GraphQLError(`Book with id "${id}" not found`, {
          extensions: { code: 'NOT_FOUND' },
        });
      }
      return book;
    },

    searchBooks: (_: unknown, { term }: { term: string }) => {
      const lowerTerm = term.toLowerCase();
      return books.filter(b =>
        b.title.toLowerCase().includes(lowerTerm) ||
        b.genre.toLowerCase().includes(lowerTerm)
      );
    },

    authors: () => authors,
    author: (_: unknown, { id }: { id: string }) => authors.find(a => a.id === id),
  },

  Mutation: {
    createBook: (_: unknown, { input }: { input: CreateBookInput }) => {
      const author = authors.find(a => a.id === input.authorId);
      if (!author) {
        throw new GraphQLError('Author not found', {
          extensions: { code: 'BAD_USER_INPUT' },
        });
      }

      const newBook: Book = {
        id: generateId(),
        ...input,
      };
      books.push(newBook);
      return newBook;
    },

    updateBook: (_: unknown, { id, input }: { id: string; input: UpdateBookInput }) => {
      const book = books.find(b => b.id === id);
      if (!book) return null;

      // Non-null schema fields ignore an explicit null
      if (input.title != null) book.title = input.title;
      if (input.genre != null) book.genre = input.genre;
      if (input.publishedYear !== undefined) book.publishedYear = input.publishedYear;
      if (input.rating !== undefined) book.rating = input.rating;
      return book;
    },

    deleteBook: (_: unknown, { id }: { id: string }) => {
      const index = books.findIndex(b => b.id === id);
      if (index === -1) {
        return { success: false, message: 'Book not found' };
      }

      books.splice(index, 1);
      return { success: true, message: 'Book deleted successfully' };
    },
  },

  // Nested resolvers for relationships
  Book: {
    author: (book: Book) => authors.find(a => a.id === book.authorId),
  },

  Author: {
    books: (author: Author) => books.filter(b => b.authorId === author.id),
  },
};

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import jwt from 'jsonwebtoken';
import { typeDefs } from './schema.js';
import { resolvers } from './resolvers.js';

export interface MyContext {
  user: { id: string; email: string; role: string } | null;
}

const JWT_SECRET = process.env.JWT_SECRET;
if (!JWT_SECRET) {
  throw new Error('JWT_SECRET is not set');
}

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

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => {
    // Extract the token from the Authorization header
    const token = req.headers.authorization?.replace('Bearer ', '');

    if (!token) {
      return { user: null };
    }

    try {
      // The payload is whatever you signed at login
      const decoded = jwt.verify(token, JWT_SECRET) as MyContext['user'];
      return { user: decoded };
    } catch (err) {
      // Invalid token - return null user, don't throw
      return { user: null };
    }
  },
  listen: { port: 4000 },
});

console.log(`Server running at ${url}`);

import { GraphQLError } from 'graphql';
import type { MyContext } from './server.js';

// Helper to enforce authentication
export function requireAuth(context: MyContext) {
  if (!context.user) {
    throw new GraphQLError('You must be logged in to perform this action', {
      extensions: {
        code: 'UNAUTHENTICATED',
        http: { status: 401 },
      },
    });
  }
  return context.user;
}

// Helper to enforce specific roles
export function requireRole(context: MyContext, role: string) {
  const user = requireAuth(context);
  if (user.role !== role) {
    throw new GraphQLError(`This action requires the "${role}" role`, {
      extensions: { code: 'FORBIDDEN' },
    });
  }
  return user;
}

// Using these in mutations (context is the third resolver argument)
export const protectedResolvers = {
  Mutation: {
    createBook: (_: unknown, args: unknown, context: MyContext) => {
      requireAuth(context);
      // ... create book logic
    },

    deleteBook: (_: unknown, args: unknown, context: MyContext) => {
      requireRole(context, 'ADMIN');
      // ... delete book logic
    },
  },
};

import { ApolloServer } from '@apollo/server';
import { GraphQLError } from 'graphql';
import { typeDefs } from './schema.js';
import { resolvers } from './resolvers.js';

interface BookInputFields {
  title?: string | null;
  publishedYear?: number | null;
  rating?: number | null;
}

// Validation: check input before processing
export function validateBookInput(input: BookInputFields) {
  const errors: string[] = [];

  if (input.title != null && input.title.trim().length < 1) {
    errors.push('Title cannot be empty');
  }
  if (input.publishedYear != null && input.publishedYear > new Date().getFullYear()) {
    errors.push('Published year cannot be in the future');
  }
  if (input.rating != null && (input.rating < 0 || input.rating > 5)) {
    errors.push('Rating must be between 0 and 5');
  }

  if (errors.length > 0) {
    throw new GraphQLError('Validation failed', {
      extensions: {
        code: 'BAD_USER_INPUT',
        validationErrors: errors,
      },
    });
  }
}

// Format errors globally before sending to the client
export const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    // Log internal errors for debugging
    if (formattedError.extensions?.code === 'INTERNAL_SERVER_ERROR') {
      console.error('Internal error:', error);
      // Don't expose internal details to the client
      return {
        message: 'An unexpected error occurred',
        extensions: { code: 'INTERNAL_SERVER_ERROR' },
      };
    }
    // Pass through expected errors (validation, auth, etc.)
    return formattedError;
  },
});

import { ApolloClient, ApolloLink, HttpLink, InMemoryCache, gql } from '@apollo/client';
import { SetContextLink } from '@apollo/client/link/context';
import { ApolloProvider, useQuery, useMutation } from '@apollo/client/react';

// Apollo Client 4: the HTTP transport is an explicit link
const httpLink = new HttpLink({ uri: 'http://localhost:4000' });

// Runs before every request, so a token saved after login is picked up
const authLink = new SetContextLink((prevContext) => {
  const token = localStorage.getItem('token');
  return {
    headers: {
      ...prevContext.headers,
      ...(token ? { authorization: `Bearer ${token}` } : {}),
    },
  };
});

// Initialize the client
const client = new ApolloClient({
  link: ApolloLink.from([authLink, httpLink]),
  cache: new InMemoryCache(),
});

interface GetBooksData {
  books: { id: string; title: string; rating: number | null; author: { name: string } }[];
}

// Define queries as tagged template literals
const GET_BOOKS = gql`
  query GetBooks($genre: String) {
    books(genre: $genre) {
      id
      title
      rating
      author {
        name
      }
    }
  }
`;

const CREATE_BOOK = gql`
  mutation CreateBook($input: CreateBookInput!) {
    createBook(input: $input) {
      id
      title
      genre
      author {
        name
      }
    }
  }
`;

// Component that fetches and displays books
function BookList({ genre }: { genre: string }) {
  const { loading, error, data } = useQuery<GetBooksData, { genre: string }>(GET_BOOKS, {
    variables: { genre },
  });

  const [createBook] = useMutation(CREATE_BOOK, {
    // Refetch the book list after creating a new book
    refetchQueries: [{ query: GET_BOOKS, variables: { genre } }],
  });

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

  return (
    <div>
      {data.books.map(book => (
        <div key={book.id}>
          <h3>{book.title}</h3>
          <p>By {book.author.name}</p>
          <span>Rating: {book.rating}/5</span>
        </div>
      ))}
      <button
        onClick={() => createBook({
          variables: { input: { title: 'Kafka on the Shore', authorId: '2', genre } },
        })}
      >
        Add sample book
      </button>
    </div>
  );
}

// Wrap your app with ApolloProvider
export function App() {
  return (
    <ApolloProvider client={client}>
      <BookList genre="Literary Fiction" />
    </ApolloProvider>
  );
}