Building GraphQL APIs

Building GraphQL APIs

GraphQL is a query language and runtime for APIs developed by Facebook. It provides a more efficient, powerful, and flexible alternative to REST by allowing clients to request exactly the data they need. This document explains how to build a GraphQL API, covering schema design, resolvers, queries, mutations, and tools using JavaScript (Node.js) as an example.

1. Setting Up a GraphQL Server

Using Apollo Server with Node.js

The most popular way to build a GraphQL API in Node.js is by using the Apollo Server library.

// Step 1: Install dependencies
npm install apollo-server graphql

// Step 2: Create a simple server
const { ApolloServer, gql } = require('apollo-server');

// Define the schema
const typeDefs = gql`
  type Query {
    hello: String
  }
`;

// Define the resolver
const resolvers = {
  Query: {
    hello: () => 'Hello world!',
  },
};

// Create the server instance
const server = new ApolloServer({ typeDefs, resolvers });

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

2. Defining a GraphQL Schema

The schema defines the types and operations available in the API. It is strongly typed and follows the SDL (Schema Definition Language).

Example Schema

type Book {
  title: String
  author: String
}

type Query {
  books: [Book]
}

In this example, we define a Book type and a query called books that returns a list of Book objects.

3. Creating Resolvers

Resolvers are functions that define how to fetch the data for each type and field in the schema.

const books = [
  { title: '1984', author: 'George Orwell' },
  { title: 'Brave New World', author: 'Aldous Huxley' },
];

const resolvers = {
  Query: {
    books: () => books,
  },
};

4. Querying the API

GraphQL APIs are typically queried using a single endpoint (e.g., /graphql) and allow clients to specify the exact fields they need.

Example Query

{
  books {
    title
    author
  }
}

Example Response

{
  "data": {
    "books": [
      { "title": "1984", "author": "George Orwell" },
      { "title": "Brave New World", "author": "Aldous Huxley" }
    ]
  }
}

5. Adding Mutations

Mutations allow clients to modify data (create, update, delete).

type Mutation {
  addBook(title: String!, author: String!): Book
}

const resolvers = {
  Query: {
    books: () => books,
  },
  Mutation: {
    addBook: (_, { title, author }) => {
      const newBook = { title, author };
      books.push(newBook);
      return newBook;
    },
  },
};

Example Mutation

mutation {
  addBook(title: "The Hobbit", author: "J.R.R. Tolkien") {
    title
    author
  }
}

6. Input Types

For more complex data structures, use input types in mutations.

input BookInput {
  title: String!
  author: String!
}

type Mutation {
  addBook(input: BookInput): Book
}

7. Nested Types and Relationships

You can define nested types and handle relationships through resolvers.

type Author {
  name: String
  books: [Book]
}

type Book {
  title: String
  author: Author
}

Resolvers can then manage how relationships are resolved:

const resolvers = {
  Book: {
    author: (book) => authors.find(a => a.id === book.authorId),
  },
};

8. GraphQL Tools and Ecosystem

• Apollo Server – For building GraphQL APIs
• GraphiQL – In-browser IDE for testing GraphQL queries
• Apollo Studio – GraphQL monitoring and insights
• GraphQL Code Generator – Generates TypeScript types and more

9. Authentication and Authorization

Authentication

Use middleware to check headers for a JWT or session token before passing context to resolvers.

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => {
    const token = req.headers.authorization || "";
    const user = getUserFromToken(token);
    return { user };
  },
});

Authorization

Check permissions inside resolvers:

Mutation: {
  addBook: (parent, args, context) => {
    if (!context.user) throw new Error("Not authorized");
    // Proceed with adding book
  }
}

10. Real-Time with Subscriptions

GraphQL supports real-time communication via subscriptions and WebSockets.

type Subscription {
  bookAdded: Book
}

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

Mutation: {
  addBook: (parent, args) => {
    const newBook = { ...args };
    books.push(newBook);
    pubsub.publish('BOOK_ADDED', { bookAdded: newBook });
    return newBook;
  }
},

Subscription: {
  bookAdded: {
    subscribe: () => pubsub.asyncIterator(['BOOK_ADDED']),
  },
}

11. GraphQL vs REST Summary

GraphQL is a powerful and flexible API technology that empowers developers to design efficient, scalable, and strongly-typed data interactions. Whether you're building a monolith or microservices, GraphQL can significantly simplify client-server communication, reduce over-fetching, and support modern frontend demands. By understanding its core components—schemas, resolvers, queries, mutations, and subscriptions—you can effectively build robust APIs tailored to real-world applications.