Sign in Subscribe
Engineering

Step-by-Step: Implementing a GraphQL API with Node.js and Apollo Server

Allan Porras

Allan Porras

— 9 min read
Step-by-Step: Implementing a GraphQL API with Node.js and Apollo Server
Photo by Douglas Lopes / Unsplash

For modern software architects and engineering leaders, the limitations of traditional REST APIs have become increasingly apparent. Issues such as over-fetching (retrieving more data than needed) and under-fetching (requiring multiple API calls to assemble a complete view) create performance bottlenecks and increase client-side complexity.

GraphQL, a query language for your API, provides a definitive solution. It empowers clients to request exactly the data they need in a single round trip, mitigating the N+1 query problem and enabling strong-typing from the client to the server.

When implementing a GraphQL API on the Node.js runtime, Apollo Server stands as the industry-standard, production-ready solution. It provides a robust, extensible, and performant framework for building and managing your data graph.

This article provides a technical, step-by-step guide for software engineers and CTOs on implementing a performant GraphQL API using Node.js and Apollo Server 4, focusing on architectural best practices, performance optimization, and practical implementation details.

Product Engineering Services

Work with our in-house Project Managers, Software Engineers and QA Testers to build your new custom software product or to support your current workflow, following Agile, DevOps and Lean methodologies.

Build with 4Geeks

1. Project Initialization and Dependency Setup

We will build our server using TypeScript to leverage static typing, which is critical for maintaining a scalable and robust GraphQL schema.

First, initialize a new Node.js project and set up the TypeScript compiler.

# 1. Create project directory
mkdir apollo-server-guide
cd apollo-server-guide

# 2. Initialize npm project
npm init -y

# 3. Install core dependencies
npm install @apollo/server graphql

# 4. Install TypeScript and development dependencies
npm install -D typescript ts-node nodemon @types/node

# 5. Create tsconfig.json
npx tsc --init --rootDir src --outDir dist --esModuleInterop --resolveJsonModule --lib es2020 --module commonjs --target es2020

Next, create a src directory and our main server file, src/index.ts.

Finally, add a dev script to your package.json for development:

"scripts": {
  "dev": "nodemon src/index.ts"
}

2. Defining the Schema (The API Contract)

The core of any GraphQL API is its schema. Defined using the Schema Definition Language (SDL), the schema is a strong contract that defines all available data types and operations (queries, mutations). This schema-first approach is architecturally superior as it allows frontend and backend teams to work in parallel against a shared, self-documenting contract.

Let's define a simple schema for a blog. Create src/schema.ts:

// src/schema.ts
export const typeDefs = `#graphql
  # A user who writes posts
  type User {
    id: ID!
    username: String!
    email: String!
    posts: [Post!]
  }

  # A blog post
  type Post {
    id: ID!
    title: String!
    content: String!
    author: User! # The user who wrote this post
  }

  # The "Query" type defines all entry points for data fetching
  type Query {
    hello: String
    users: [User!]
    user(id: ID!): User
    posts: [Post!]
    post(id: ID!): Post
  }

  # Input type for creating a new user
  input CreateUserInput {
    username: String!
    email: String!
  }

  # The "Mutation" type defines all entry points for data modification
  type Mutation {
    createUser(input: CreateUserInput!): User
    deleteUser(id: ID!): Boolean
  }
`;

Key Architectural Points:

  • ID!: This scalar type signifies a unique identifier. The ! denotes that the field is Non-Nullable. This strictness is a key feature of GraphQL, preventing entire classes of null-pointer errors.
  • type Query: This is the primary entry point for all read operations.
  • type Mutation: This is the primary entry point for all write operations (CUD). Using a single input type (e.g., CreateUserInput) for mutations is a best practice, allowing you to add new fields without breaking client compatibility.
  • Relational Link: Notice the author: User! field on the Post type. This defines the graph relationship. We will implement the logic for this relationship in the resolvers.

3. Implementing Resolvers (The Execution Logic)

Resolvers are functions that provide the instructions for turning a GraphQL operation into data. They are the "logic" behind the "contract" of the schema. Each field in your schema must be backed by a corresponding resolver.

Let's start with a mock data source and implement our resolvers. Create src/resolvers.ts:

// src/resolvers.ts

// Mock data
const db = {
  users: [
    { id: '1', username: 'alice', email: 'alice@example.com' },
    { id: '2', username: 'bob', email: 'bob@example.com' },
  ],
  posts: [
    { id: '101', title: 'GraphQL is Great', content: '...', authorId: '1' },
    { id: '102', title: 'Apollo Server Deep Dive', content: '...', authorId: '2' },
    { id: '103', title: 'Node.js Performance', content: '...', authorId: '1' },
  ],
};

export const resolvers = {
  Query: {
    hello: () => 'Hello from Apollo Server!',
    
    // Resolver for fetching all users
    users: () => db.users,
    
    // Resolver for fetching a single user by ID
    user: (parent, args: { id: ID }, context, info) => {
      return db.users.find((user) => user.id === args.id);
    },
    
    posts: () => db.posts,
    post: (parent, args: { id: ID }) => {
      return db.posts.find((post) => post.id === args.id);
    },
  },

  Mutation: {
    // Resolver for creating a new user
    createUser: (parent, { input }: { input: { username: string, email: string } }) => {
      const newUser = {
        id: (db.users.length + 1).toString(),
        ...input,
      };
      db.users.push(newUser);
      return newUser;
    },
    
    // Resolver for deleting a user
    deleteUser: (parent, { id }: { id: ID }) => {
      const index = db.users.findIndex((user) => user.id === id);
      if (index === -1) return false;
      db.users.splice(index, 1);
      // Also remove their posts (demonstrating transactional logic)
      db.posts = db.posts.filter((post) => post.authorId !== id);
      return true;
    },
  },

  // --- Relational Resolvers ---
  // These resolvers "connect" the graph.

  User: {
    // This resolver fires when a query asks for a User's `posts` field
    posts: (parentUser) => {
      console.log(`Fetching posts for user: ${parentUser.id}`);
      return db.posts.filter((post) => post.authorId === parentUser.id);
    },
  },

  Post: {
    // This resolver fires when a query asks for a Post's `author` field
    author: (parentPost) => {
      console.log(`Fetching author for post: ${parentPost.id}`);
      return db.users.find((user) => user.id === parentPost.authorId);
    },
  },
};

// Type definitions for resolver arguments
type ID = string;

Resolver Argument Breakdown:

A resolver function receives four arguments. Understanding these is critical for implementation:

  1. parent: The object returned from the parent resolver. For Query.users, this is null or undefined. For Post.author, parent is the Post object (parentPost in our example).
  2. args: An object containing the arguments passed to the field in the GraphQL query (e.g., args.id for the user(id: ID!) query).
  3. context: This is the most important argument for production systems. It's an object shared across all resolvers for a single request. It is used to pass request-specific information like authentication data (e.g., the logged-in user), database connection pools, and data loaders.
  4. info: An object containing the abstract syntax tree (AST) and other information about the query being executed. It's primarily used for advanced use cases like query optimization.

4. Instantiating and Running Apollo Server

Now, let's wire up our typeDefs and resolvers in src/index.ts to start the server.

// src/index.ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { typeDefs } from './schema';
import { resolvers } from './resolvers';

// Define the shape of our context.
// This is empty for now but will be crucial later.
export interface MyContext {
  // Example: token?: string;
}

async function startServer() {
  // The ApolloServer constructor requires two parameters: 
  // your schema definition and your set of resolvers.
  const server = new ApolloServer<MyContext>({
    typeDefs,
    resolvers,
  });

  // startStandaloneServer is a helper function that quickly
  // gets Apollo Server up and running.
  const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 },
  });

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

startServer();

Run the server with npm run dev. You will see the output:

🚀 Server ready at: http://localhost:4000/

Navigate to http://localhost:4000/ in your browser. You will be greeted by the Apollo Server Sandbox, an interactive IDE for executing GraphQL operations.

Test Operations:

Execute the following mutation to create a user:

mutation CreateNewUser {
  createUser(input: { username: "charlie", email: "charlie@example.com" }) {
    id
    username
  }
}

Now, execute this query to fetch all data and see the graph relationships in action:

query GetAllPostsWithAuthors {
  posts {
    id
    title
    author {
      id
      username
      email
    }
  }
}

If you check your server console, you'll see the logs from our relational resolvers:

Fetching author for post: 101

Fetching author for post: 102

Fetching author for post: 103

This demonstrates a critical performance anti-pattern: the N+1 Query Problem. We fetched 3 posts, which then triggered 3 additional lookups for the authors. We will solve this next.

5. Solving the N+1 Problem with Context and DataLoaders

The N+1 problem is the single most common performance pitfall in GraphQL. The solution is to use batching and caching, which is perfectly implemented by Facebook's dataloader library.

We will instantiate our DataLoader inside the context function. This ensures that batching is scoped per-request, which is a critical architectural pattern.

1. Install dataloader:

npm install dataloader

2. Create DataLoaders:

We'll create a UserLoader. Its job is to accept an array of user IDs, fetch them all in a single batch operation, and then return them in the correct order.

Create src/loaders.ts:

// src/loaders.ts
import DataLoader from 'dataloader';
import { db } from './db'; // Assume db is exported from a separate file now

// A batch loading function for users
const batchUsers = async (ids: readonly string[]) => {
  console.log(`BATCH: Fetching users for IDs: ${ids}`);
  
  // In a real app, this would be a single SQL query:
  // SELECT * FROM users WHERE id IN (...)
  const users = db.users.filter((user) => ids.includes(user.id));

  // Data must be returned in the same order as the keys.
  // We'll map IDs to users to ensure this.
  const userMap = new Map(users.map((user) => [user.id, user]));
  return ids.map((id) => userMap.get(id) || new Error(`No user found for ID ${id}`));
};

export const createLoaders = () => ({
  user: new DataLoader(batchUsers),
});

(Note: For this to work, refactor your mock db from resolvers.ts into its own file, e.g., src/db.ts, and import it in both resolvers.ts and loaders.ts.)

Product Engineering Services

Work with our in-house Project Managers, Software Engineers and QA Testers to build your new custom software product or to support your current workflow, following Agile, DevOps and Lean methodologies.

Build with 4Geeks

3. Update Context and Server Initialization:

Now, we modify src/index.ts to create new loader instances for every request and pass them via the context.

// src/index.ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { typeDefs } from './schema';
import { resolvers } from './resolvers';
import { createLoaders } from './loaders'; // Import loaders
import { db } from './db'; // Import db

// Define the shape of our context
export interface MyContext {
  db: typeof db;
  loaders: ReturnType<typeof createLoaders>;
  // Example: You would also pass auth info here
  // userId?: string;
}

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

  const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 },
    
    // This context function runs on every request
    context: async ({ req }) => {
      // Example: Authenticate user from `req.headers.authorization`
      // const userId = getUserIdFromToken(req.headers.authorization);

      return {
        // We create new DataLoaders for each request
        loaders: createLoaders(),
        // We can also pass our DB (or connection pool)
        db,
        // userId,
      };
    },
  });

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

startServer();

4. Refactor Resolvers to Use DataLoaders:

Finally, update src/resolvers.ts to use the loaders from the context instead of performing direct lookups.

// src/resolvers.ts (Partial)
import { MyContext } from './index'; // Import the context type

export const resolvers = {
  Query: {
    // ... other query resolvers ...
    // Pass context.db to resolvers that need it
    users: (parent, args, context: MyContext) => context.db.users,
    user: (parent, args: { id: ID }, context: MyContext) => {
      return context.db.users.find((user) => user.id === args.id);
    },
    // ...
  },
  
  Mutation: {
    // ... mutation resolvers ...
    // Use context.db for modifications
    createUser: (parent, { input }, context: MyContext) => {
      // ... logic using context.db.users ...
    },
    // ...
  },

  User: {
    posts: (parentUser, args, context: MyContext) => {
      // This is still an N+1, but for posts.
      // You would create a PostLoader to solve this.
      console.log(`Fetching posts for user: ${parentUser.id}`);
      return context.db.posts.filter((post) => post.authorId === parentUser.id);
    },
  },

  Post: {
    // REFACTORED: This resolver now uses the DataLoader
    author: (parentPost, args, context: MyContext) => {
      // Instead of a direct lookup...
      // return context.db.users.find((user) => user.id === parentPost.authorId);
      
      // We "load" the ID. DataLoader will batch and cache this.
      console.log(`SCHEDULING: Author load for post: ${parentPost.id}`);
      return context.loaders.user.load(parentPost.authorId);
    },
  },
};

Now, re-run the GetAllPostsWithAuthors query from earlier. Look at your server console:

SCHEDULING: Author load for post: 101
SCHEDULING: Author load for post: 102
SCHEDULING: Author load for post: 103
BATCH: Fetching users for IDs: 1,2

The N+1 problem is solved. DataLoader collected all the required authorIds (1, 2, 1) across the parallel resolver executions, deduplicated them (1, 2), and fired a single batch request. This is a massive performance gain and a non-negotiable pattern for production-grade GraphQL.

6. Production Considerations

While the above forms a solid foundation, a CTO must consider the following for a production deployment:

  • Error Handling: By default, any exception thrown in a resolver returns a generic "Internal Server Error." Use Apollo's GraphQLError class to provide specific error codes and messages to the client (e.g., FORBIDDEN, BAD_USER_INPUT).
  • Authentication & Authorization: Authentication should be handled in the context function by validating a token from the request headers and attaching the user's ID to the context. Authorization logic can then be placed at the top of resolvers (e.g., if (context.userId !== post.authorId) throw new GraphQLError(...)) or handled declaratively using schema directives.
  • Schema Organization: For large applications, monolithic schema.ts and resolvers.ts files are unmaintainable. The best practice is to co-locate types, resolvers, and data models by feature or domain (e.g., in a /features/User directory) and then merge them programmatically.
  • Persistent Data Layer: Replace the mock db with a real database connection (e.g., a PrismaClient instance or a knex connection pool) and pass it via the context object, just as we did with the loaders.
  • Monitoring: A GraphQL API is a single endpoint (/graphql), which makes traditional path-based REST monitoring obsolete. Use a tool like Apollo Studio to get field-level performance metrics, trace query execution, and manage your schema registry.

Conclusion

You have successfully implemented a production-ready GraphQL API with Node.js and Apollo Server. You have defined a strong schema, implemented resolver logic, and, most importantly, architected a performant data-fetching layer by using the context API and DataLoader to solve the N+1 query problem.

This stack provides an unparalleled developer experience and a highly efficient communication layer for modern applications. By building on these patterns, your engineering organization can effectively manage complex data graphs, decouple client and server development, and deliver highly responsive applications.

Read more