How to Implement a GraphQL API in Node.js

REST APIs have fixed endpoints that return fixed data shapes. Clients often receive too much data containing fields they do not need, or too little data requiring multiple requests to assemble one view. GraphQL exposes a single endpoint where clients specify exactly the fields they need in each request, eliminating over-fetching and under-fetching. This is especially valuable for mobile clients where bandwidth is limited.

Install @apollo/server and graphql packages. Apollo Server is the most popular GraphQL server implementation for Node.js. Create your server entry point file. Apollo Server can run as a standalone HTTP server or integrate with an existing Express application. For adding GraphQL to an existing Express API, use the expressMiddleware function from Apollo Server.

A GraphQL schema is written in the Schema Definition Language. Define your types describing the shape of your data. Every schema must have a Query type defining the available read operations. Define a Mutation type for write operations. Define input types for mutation arguments. The schema is the contract between the server and all clients and documents every possible operation.

A resolver is a function that returns the data for a specific field in the schema. Create a resolvers object that mirrors the structure of your type definitions. Each resolver function receives four arguments: parent which is the result of the parent resolver, args which contains the arguments from the query, context which is a shared object for the request, and info which contains execution metadata.

Query resolvers fetch and return data. Inside a query resolver, call your data source such as a database model or an external API. Return the data in the shape that your GraphQL type expects. If a field is nullable in the schema, you can return null. If it is non-nullable, returning null causes a GraphQL error. Match the return shape to the type definition precisely.

Mutation resolvers modify data and return the result. Accept arguments through the args parameter and use them to create, update, or delete records in your database. After the operation, return the modified record or a success indicator as defined by the return type in your schema. Wrap database operations in try-catch and throw GraphQL errors using the GraphQLError class for proper error formatting.

The context is a shared object passed to every resolver in a request. Use it to carry authentication information. In the context function provided to Apollo Server, extract and verify the JWT from the request headers. Attach the decoded user object to the context. In resolvers that require authentication, check if the user exists in the context and throw an AuthenticationError if not.

A common GraphQL performance issue is the N plus one problem where fetching a list of items and their related data results in one database query for the list plus one additional query per item. Install the dataloader package and create DataLoaders for each relationship. DataLoader batches all individual lookups that occur within the same tick of the Event Loop into a single database query using an IN clause, dramatically reducing database round trips.