TypeScript & GraphQL: Building a Simple API with Type Safety

Written by

learnmodernjavascript

in

In the world of web development, APIs (Application Programming Interfaces) are the backbone of modern applications. They enable different software systems to communicate and exchange data, powering everything from social media feeds to e-commerce platforms. While REST APIs have long been the standard, GraphQL is rapidly gaining popularity as a powerful alternative. GraphQL offers a more efficient and flexible approach to data fetching, allowing clients to request precisely the data they need, reducing over-fetching and under-fetching. This tutorial will guide you through building a simple, type-safe API using TypeScript and GraphQL, empowering you to create robust and scalable backend solutions.

Why TypeScript and GraphQL?

Before we dive into the code, let’s explore why TypeScript and GraphQL are a winning combination:

  • Type Safety: TypeScript adds static typing to JavaScript, catching potential errors during development, and improving code maintainability. This is especially beneficial when working with APIs, ensuring data consistency and reducing runtime bugs.
  • GraphQL’s Efficiency: GraphQL allows clients to request specific data, avoiding the over-fetching and under-fetching issues common with REST APIs. This leads to improved performance and reduced bandwidth usage.
  • Developer Experience: GraphQL’s schema-driven approach provides clear documentation and autocompletion, enhancing the developer experience. TypeScript’s type definitions further improve this by providing type-checking for GraphQL queries and mutations.

Setting Up Your Project

Let’s get started by setting up our project. We’ll use Node.js and npm (or yarn) to manage our dependencies. If you don’t have Node.js and npm installed, download them from the official website. Create a new project directory and initialize a new Node.js project:

mkdir typescript-graphql-api
cd typescript-graphql-api
npm init -y

Next, install the necessary dependencies:

npm install graphql @graphql-tools/schema graphql-yoga typescript ts-node @types/node
npm install --save-dev @types/graphql
npm install --save-dev tsc-watch
npm install --save-dev nodemon

Here’s a breakdown of these dependencies:

  • graphql: The core GraphQL library.
  • @graphql-tools/schema: Tools for building GraphQL schemas.
  • graphql-yoga: A simple, fully-featured GraphQL server.
  • typescript: The TypeScript compiler.
  • ts-node: Allows us to execute TypeScript code directly.
  • @types/node: TypeScript type definitions for Node.js.
  • @types/graphql: TypeScript type definitions for GraphQL.
  • tsc-watch: A utility to watch for changes in TypeScript files and recompile.
  • nodemon: A utility to watch for changes in files and restart the server.

Now, let’s configure TypeScript. Create a tsconfig.json file in your project root with the following content:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "outDir": "./dist",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "sourceMap": true
  },
  "include": ["src/**/*"]
}

This configuration tells the TypeScript compiler how to compile your code. Important settings include:

  • target: Specifies the JavaScript version to compile to (ES2016 in this case).
  • module: Specifies the module system (CommonJS is used here).
  • outDir: Defines where the compiled JavaScript files will be placed.
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • forceConsistentCasingInFileNames: Enforces consistent casing in file names.
  • strict: Enables strict type checking.
  • skipLibCheck: Skips type checking of declaration files.
  • sourceMap: Generates source map files for debugging.
  • include: Specifies which files to include in the compilation.

Creating the GraphQL Schema

The GraphQL schema defines the structure of your API, including the types of data you can query and mutate. Create a new directory called src and a file named schema.ts inside it. This is where your schema will reside.

// src/schema.ts
import { buildSchema } from 'graphql';

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

export default schema;

In this example, we define a simple schema with a single query called hello, which returns a string. The buildSchema function from the graphql library parses the schema definition string and creates a GraphQL schema object.

Implementing Resolvers

Resolvers are functions that provide the actual data for your GraphQL queries and mutations. Create a new file named resolvers.ts in the src directory:


// src/resolvers.ts
const resolvers = {
  Query: {
    hello: () => 'Hello, world!',
  },
};

export default resolvers;

Here, we define a resolver for the hello query. When a client queries the hello field, this resolver function will be executed, returning the string “Hello, world!”.

Setting Up the GraphQL Server

Now, let’s create the GraphQL server using graphql-yoga. Create a file named index.ts in the src directory:


// src/index.ts
import { GraphQLServer } from 'graphql-yoga';
import schema from './schema';
import resolvers from './resolvers';

const server = new GraphQLServer({
  typeDefs: schema,
  resolvers,
});

server.start(() => console.log('Server is running on http://localhost:4000'));

This code does the following:

  • Imports the GraphQLServer class from graphql-yoga.
  • Imports the schema and resolvers we defined earlier.
  • Creates a new GraphQLServer instance, passing in the schema and resolvers.
  • Starts the server, which will be accessible at http://localhost:4000 by default.

Running the Server

Before running the server, let’s add some scripts to your package.json to make development easier. Open your package.json file and add the following scripts inside the "scripts" object:


  "scripts": {
    "start": "ts-node src/index.ts",
    "dev": "tsc-watch --onSuccess "node dist/index.js"",
    "build": "tsc"
  },

These scripts do the following:

  • start: Runs the server using ts-node, which executes TypeScript files directly. This is useful for development, but not for production.
  • dev: Uses tsc-watch to watch for changes in your TypeScript files and automatically recompile them. When the compilation is successful, it runs the compiled JavaScript code using node.
  • build: Compiles your TypeScript code into JavaScript using the TypeScript compiler.

Now, run the development server using the following command:

npm run dev

This will start the server and watch for changes in your src directory. Open your web browser and navigate to http://localhost:4000. You should see the GraphQL Playground, an interactive environment where you can test your GraphQL queries and mutations.

Testing Your API

In the GraphQL Playground, you can now test your hello query. Enter the following query in the left pane and click the play button:


query {
  hello
}

You should see the following result in the right pane:


{
  "data": {
    "hello": "Hello, world!"
  }
}

Congratulations! You’ve successfully built a simple GraphQL API with TypeScript.

Adding More Complex Types and Queries

Let’s expand our API to handle more complex data. We’ll create a simple API for managing books. First, modify your schema.ts file to include a Book type and a query to fetch a list of books:


// src/schema.ts
import { buildSchema } from 'graphql';

const schema = buildSchema(`
  type Book {
    title: String!
    author: String!
    pages: Int
  }

  type Query {
    hello: String
    books: [Book!]
  }
`);

export default schema;

Here, we’ve defined a Book type with fields for title, author, and pages. The exclamation mark (!) indicates that a field is non-nullable. We’ve also added a books query, which returns a list of Book objects.

Next, update your resolvers.ts file to include the resolver for the books query:


// src/resolvers.ts
const books = [
  { title: 'The Lord of the Rings', author: 'J.R.R. Tolkien', pages: 1178 },
  { title: 'Pride and Prejudice', author: 'Jane Austen', pages: 432 },
  { title: '1984', author: 'George Orwell', pages: 328 },
];

const resolvers = {
  Query: {
    hello: () => 'Hello, world!',
    books: () => books,
  },
};

export default resolvers;

This resolver simply returns a hardcoded array of book objects. In a real-world application, you would typically fetch this data from a database.

Restart your server (if it’s not already running) and go back to the GraphQL Playground. You can now query for books using the following query:


query {
  books {
    title
    author
  }
}

You should see a list of books with their titles and authors.

Adding Mutations

Mutations allow you to modify data. Let’s add a mutation to create a new book. Update your schema.ts file:


// src/schema.ts
import { buildSchema } from 'graphql';

const schema = buildSchema(`
  type Book {
    title: String!
    author: String!
    pages: Int
  }

  type Query {
    hello: String
    books: [Book!]
  }

  type Mutation {
    addBook(title: String!, author: String!, pages: Int): Book
  }
`);

export default schema;

We’ve added a Mutation type with an addBook mutation. This mutation takes title, author, and pages as input and returns a Book object. Now, update your resolvers.ts file:


// src/resolvers.ts
const books = [
  { title: 'The Lord of the Rings', author: 'J.R.R. Tolkien', pages: 1178 },
  { title: 'Pride and Prejudice', author: 'Jane Austen', pages: 432 },
  { title: '1984', author: 'George Orwell', pages: 328 },
];

const resolvers = {
  Query: {
    hello: () => 'Hello, world!',
    books: () => books,
  },
  Mutation: {
    addBook: (parent: any, args: { title: string; author: string; pages?: number }) => {
      const newBook = { title: args.title, author: args.author, pages: args.pages };
      books.push(newBook);
      return newBook;
    },
  },
};

export default resolvers;

Here, we’ve added a resolver for the addBook mutation. This resolver takes the book details as arguments, creates a new book object, adds it to the books array, and returns the new book. Restart your server and you can now test the mutation in the GraphQL Playground:


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

After running this mutation, you can query for books again, and you should see the newly added book in the list.

Input Validation and Error Handling

In a real-world application, you’ll want to validate the input data and handle errors gracefully. For example, you might want to ensure that the title and author fields are not empty, and that the pages field is a positive number. You can achieve this by adding validation logic within your resolvers. Here’s an example:


// src/resolvers.ts
const books = [
  { title: 'The Lord of the Rings', author: 'J.R.R. Tolkien', pages: 1178 },
  { title: 'Pride and Prejudice', author: 'Jane Austen', pages: 432 },
  { title: '1984', author: 'George Orwell', pages: 328 },
];

const resolvers = {
  Query: {
    hello: () => 'Hello, world!',
    books: () => books,
  },
  Mutation: {
    addBook: (parent: any, args: { title: string; author: string; pages?: number }) => {
      if (!args.title || args.title.trim() === '') {
        throw new Error('Title cannot be empty');
      }
      if (!args.author || args.author.trim() === '') {
        throw new Error('Author cannot be empty');
      }
      if (args.pages !== undefined && args.pages < 0) {
        throw new Error('Pages must be a positive number');
      }
      const newBook = { title: args.title, author: args.author, pages: args.pages };
      books.push(newBook);
      return newBook;
    },
  },
};

export default resolvers;

In this example, we’ve added checks to ensure that the title and author are not empty strings, and that pages is a positive number. If any of these conditions are not met, we throw an error. GraphQL will automatically handle these errors and return them to the client in a structured format. When a GraphQL error is thrown, the client receives a response that includes an `errors` array containing details about the error. The error object typically includes a message, and can also include the location in the schema where the error occurred.

Best Practices and Advanced Features

Here are some best practices and advanced features to consider when building GraphQL APIs with TypeScript:

  • Use a Database: Instead of hardcoding data, connect your API to a database like PostgreSQL, MongoDB, or MySQL. You’ll need a database driver library for your chosen database, and you’ll need to modify your resolvers to interact with the database.
  • Authentication and Authorization: Implement authentication and authorization to secure your API. You can use libraries like Passport.js or create your own authentication middleware.
  • Data Loaders: Use data loaders (e.g., DataLoader) to optimize data fetching by batching and caching database requests. This can significantly improve performance, especially when dealing with complex relationships between data entities.
  • Subscriptions: Implement subscriptions to enable real-time updates. GraphQL subscriptions allow clients to subscribe to specific events and receive updates whenever those events occur.
  • Pagination: Implement pagination to handle large datasets efficiently. GraphQL provides several ways to implement pagination, including offset-based and cursor-based pagination.
  • Code Generation: Use code generation tools like GraphQL Code Generator to generate TypeScript types and resolvers from your GraphQL schema. This can significantly reduce boilerplate code and improve type safety.
  • Testing: Write unit tests and integration tests to ensure your API is working correctly. Use testing frameworks like Jest or Mocha.
  • Error Handling: Implement robust error handling to handle unexpected errors and provide informative error messages to the client. Consider using a centralized error handling mechanism.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • Incorrect Schema Definition: Typos or syntax errors in your schema definition can cause your server to fail to start or to return unexpected results. Double-check your schema definition for any errors. Use the GraphQL Playground’s built-in validation to check your schema.
  • Incorrect Resolver Implementation: Make sure your resolvers are correctly fetching and returning the data that your queries and mutations expect. Use console logs to debug your resolvers and inspect the data they are returning.
  • CORS Issues: If you’re trying to access your API from a different domain, you may encounter CORS (Cross-Origin Resource Sharing) errors. Configure your server to allow requests from the appropriate origin. In graphql-yoga, you can configure CORS options when creating the server.
  • Type Errors: TypeScript’s type checking can help catch errors, but you may still encounter type-related issues. Carefully check your types and make sure they are consistent throughout your code. Use TypeScript’s error messages to guide you.
  • Dependency Issues: Make sure you have installed all the necessary dependencies and that they are compatible with each other. Check the documentation for your libraries to ensure you’re using the correct versions.

Key Takeaways

  • TypeScript and GraphQL are a powerful combination for building type-safe and efficient APIs.
  • GraphQL allows clients to request specific data, reducing over-fetching and improving performance.
  • GraphQL schemas define the structure of your API, while resolvers provide the data.
  • Use validation and error handling to create robust APIs.
  • Explore advanced features like authentication, authorization, and subscriptions.

FAQ

Q: What is GraphQL?

A: GraphQL is a query language for your API, and a server-side runtime for executing queries with your data. It provides an alternative to REST APIs, offering more flexibility and efficiency in data fetching.

Q: Why use TypeScript with GraphQL?

A: TypeScript adds static typing to JavaScript, which helps catch errors early, improves code maintainability, and provides better developer tooling. It’s particularly beneficial when working with APIs.

Q: What are resolvers in GraphQL?

A: Resolvers are functions that provide the actual data for your GraphQL queries and mutations. They define how to fetch or modify data based on the client’s requests.

Q: How does GraphQL compare to REST?

A: GraphQL allows clients to request specific data, avoiding over-fetching and under-fetching. REST APIs typically return fixed data structures, which can lead to inefficiencies. GraphQL provides more flexibility and can improve performance.

Conclusion

By combining the type safety of TypeScript with the flexibility of GraphQL, you can build powerful, efficient, and maintainable APIs. This tutorial has provided a solid foundation for building your own GraphQL APIs. As you continue your journey, experiment with different features, explore advanced concepts, and build applications that leverage the power of GraphQL. The combination of TypeScript and GraphQL offers a modern and effective approach to API development, providing a robust and scalable solution for your backend needs. Embrace the flexibility and efficiency of GraphQL and TypeScript to create APIs that meet the demands of today’s applications.

More posts