What I Learned Replacing Our Node.js REST APIs with a TypeScript GraphQL Server

If you’ve ever shipped a Node.js REST API and watched frontend devs ask for “just one more field” or “can we filter this differently?”, you know the pain. We were drowning in endpoints, versioning chaos, and a growing backlog of tiny requests. When we switched to a TypeScript GraphQL server, things changed—sometimes in ways we didn’t expect. Here’s what actually happens in your code and workflow when you make the jump.

REST vs. GraphQL: What Changes in Practice

Switching from REST to GraphQL isn’t just about swapping fetch calls for queries. The biggest shift is how your API and frontend developers interact.

With REST, you define the shape of each endpoint. Want a list of users? /users. Need their emails? Maybe /users/emails or a new property added to /users. Every change is a negotiation.

GraphQL flips this: your schema is a contract, but clients decide what fields they want. Suddenly, you’re not writing new endpoints for every request—you’re thinking in terms of types and resolvers. For us, this meant less argument over endpoint design, but a lot more upfront schema planning.

Code Example: REST Endpoint vs. GraphQL Resolver

Here’s a classic REST handler in Node.js using Express:

// REST Example: Express endpoint for user lookup
app.get('/users/:id', async (req, res) => {
  const user = await db.findUserById(req.params.id);
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  // Only returns fixed fields
  res.json({ id: user.id, name: user.name, email: user.email });
});

Now, the same logic in a GraphQL resolver (using Apollo Server and TypeScript):

// GraphQL Example: User resolver in Apollo Server
const resolvers = {
  Query: {
    user: async (_: any, args: { id: string }) => {
      const user = await db.findUserById(args.id);
      if (!user) return null; // GraphQL returns null if not found
      return user; // Clients pick fields they want
    },
  },
};

The thing is, clients can now query just the fields they need:

query {
  user(id: "123") {
    name
    email
  }
}

No more endpoint sprawl. But you have to be careful—your schema is your API’s foundation, and it needs to be crisp.

Type Safety: Actual Benefits and Gotchas

Using TypeScript with GraphQL is a game changer if you’re tired of runtime surprises. In REST, you can slap any on request bodies and keep moving. With GraphQL, your schema is your contract, and TypeScript helps enforce it.

We started using graphql-code-generator to generate TypeScript types from our schema. Suddenly, resolver inputs and outputs were typed based on actual queries. No more guessing if a field exists or what shape an argument takes.

But here’s the honest part: you’ll fight with types at first. If you’re used to duck typing in JavaScript, GraphQL’s strictness can feel like handcuffs. It pays off in reliability, but expect some friction.

Code Example: TypeScript Types from GraphQL Schema

Suppose your schema defines a User type:

type User {
  id: ID!
  name: String!
  email: String!
  phone: String
}

The generated TypeScript type might look like:

// Generated from GraphQL schema
export interface User {
  id: string;
  name: string;
  email: string;
  phone?: string; // Optional field
}

When you write your resolver, TypeScript will yell at you if you return a non-conforming object:

const resolvers = {
  Query: {
    user: async (_: any, args: { id: string }): Promise<User | null> => {
      const user = await db.findUserById(args.id);
      if (!user) return null;
      // TypeScript checks that user matches User interface
      return user;
    },
  },
};

I spent a weekend debugging a mismatch between schema types and database models. If you use TypeScript, make sure your models and GraphQL schema stay in sync, or you’ll lose the benefits.

Frontend Collaboration: Less Negotiation, More Ownership

One of the biggest surprises was how GraphQL changed our frontend-backend dynamic. With REST, every new requirement meant a backend ticket. “Can you add this field to the response?” “Can you filter the users here?”

GraphQL put more power in frontend hands. They could query for just what they needed, combine multiple types, and cut down on over-fetching. This sped up development, but it also meant we had to educate the frontend team about the schema and how to avoid “N+1” pitfalls.

Code Example: Combining Data in One Query

With REST, you might hit /users/123 and then /users/123/posts. With GraphQL:

query {
  user(id: "123") {
    name
    posts {
      title
      createdAt
    }
  }
}

This lets them fetch related data in a single request. On the backend, you’ll need to write resolvers for nested types:

const resolvers = {
  User: {
    posts: async (parent: User) => {
      // parent is the user object
      return db.findPostsByUserId(parent.id);
    },
  },
};

Notice how you can compose data easily. But careful—if you naively fetch posts for every user in a list, you’ll run into performance issues. We eventually implemented DataLoader to batch queries and avoid the dreaded “N+1” problem.

Error Handling: New Patterns

REST APIs usually return HTTP codes (404, 500, etc.), and clients handle them accordingly. GraphQL uses a different approach: responses always return 200 OK, with errors inside the response body.

This can trip you up if you’re used to relying on HTTP status codes for flow control. You need to throw errors inside resolvers, and clients need to check the errors field in GraphQL responses.

We made a habit of wrapping resolver logic in try/catch, and using Apollo’s ApolloError for custom errors:

import { ApolloError } from 'apollo-server';

// Example: Custom error in resolver
const resolvers = {
  Query: {
    user: async (_: any, args: { id: string }) => {
      try {
        const user = await db.findUserById(args.id);
        if (!user) {
          throw new ApolloError('User not found', 'USER_NOT_FOUND');
        }
        return user;
      } catch (err) {
        throw new ApolloError('Internal server error', 'INTERNAL_ERROR');
      }
    },
  },
};

This pattern helps clients get meaningful error codes and messages, but it’s a shift from REST conventions.

Common Mistakes

1. Overfetching or Underfetching Data

It’s tempting to expose all fields on types, but doing so can lead to overfetching (clients ask for too much data) or underfetching (missing fields). Be deliberate about your schema. Don’t let your database model dictate your public API.

2. Ignoring the N+1 Problem

If your resolvers fetch related data (like posts for each user), you’ll hit the database repeatedly—once per user. This can tank performance. Use batching tools like DataLoader, and educate frontend devs about efficient queries.

3. Not Keeping Types in Sync

If your TypeScript models drift from your GraphQL schema, you’ll get runtime errors or weird bugs. Use codegen tools, and automate your checks. Our team ran into this last month—one mismatch caused a cascade of bugs.

Key Takeaways

• GraphQL cuts down on endpoint sprawl, but requires careful schema design
• TypeScript and GraphQL together provide real type safety—if you keep your types synced
• Frontend teams gain more flexibility, but need guidance to avoid performance pitfalls
• Error handling shifts from HTTP codes to error objects, which changes client logic
• Watch out for overfetching and the N+1 problem—batching is your friend

Making the switch from REST to a TypeScript GraphQL server isn't a magic fix, but it changes how your team builds APIs. If you’re tired of endpoint chaos and want more predictable contracts, it’s worth exploring. Just be ready for some new challenges—and a few weekends spent debugging types.

---

If you found this helpful, check out more programming tutorials on our blog. We cover Python, JavaScript, Java, Data Science, and more.