Why I Am Not the Biggest Fan of GraphQL - ProductFTW #55

I am not the most technical person. My focus is on product development, but I make it a point to dip my toes into the technical landscape so that I can ask the right questions, challenge assumptions, and ensure feasibility before committing to a feature.

Recently, I have been working with partners who have switched from REST to GraphQL. While I understand why GraphQL is powerful, I have come to realize that it presents unique challenges from a product management perspective.

GraphQL is flexible, allowing you to pull only the data you need instead of making multiple API calls. Instead of five separate requests, you can retrieve everything in one efficient call. That is great in theory. But in practice, it requires an entirely different way of thinking, and if not managed well, it can create complexity rather than reducing it.

From a product development standpoint, GraphQL introduces friction that REST does not. It makes early-stage product scoping more difficult, forces teams to rely heavily on accurate technical documentation, and increases the initial startup cost of development.

The Product Challenge: The Need for Clarity in Early Development

When writing product requirements, I focus on what the product needs to do, not how the technology should implement it. That is the job of my engineering counterparts. But with GraphQL, that line becomes blurred.

With REST, my team can take my requirements and test API calls directly to see what the API can and cannot do. This means we can immediately identify gaps between what we want and what is possible.

With GraphQL, that early discovery phase becomes much harder because it is so flexible. Instead of receiving clear-cut endpoints, developers need to construct their queries from scratch, deciding which fields to request and how the data should be structured. This flexibility means that:

• The team has to spend extra time designing API requests rather than focusing on building features.
• There is room for misinterpretation, where developers assume certain data is available when it is not.
• Product teams are forced to rely on documentation to determine what is possible rather than testing API calls in a straightforward way.

If the documentation is lacking or outdated, the entire development process suffers.

The Documentation Problem: When Flexibility Becomes a Liability

One of my biggest frustrations with GraphQL is that it requires teams to fully trust the documentation. Unlike REST, where you can often figure things out by calling a well-defined endpoint, GraphQL demands that you know what you want to return before you start coding.

If the documentation is incomplete, unclear, or incorrect, you are stuck. Your team is left guessing how to structure requests, which can lead to:

• Inconsistent data formats that break the product experience.
• Additional development cycles spent debugging issues that could have been avoided.
• Wasted time asking the API provider for clarification instead of moving forward.

I have had to explain this challenge to non-technical stakeholders, and the way I put it is simple:

“You have to know exactly what you want before you start coding, and you have to trust that the partner’s documentation is accurate. If either of those things fails, your team will fail.”

A Real-World Example: The Phone Number Formatting Problem

I ran into this issue firsthand when trying to integrate a client with a third-party API.

We were using their GraphQL API, but there was no clear documentation on how to format phone numbers when sending requests. In REST, this would have been obvious—we would send a request, get an error, and immediately see the expected format. With GraphQL, the flexibility meant that:

• The API did not reject our request outright; it simply returned incomplete or incorrect results.
• We had no way to confirm whether we were formatting the data correctly.
• We wasted hours troubleshooting something that should have been self-explanatory.

This is a prime example of how GraphQL introduces unnecessary friction in product development. The promise of flexibility comes at the cost of clarity and immediate validation.

The Trade-Offs: When GraphQL is Worth It (and When It Is Not)

That said, I do not hate GraphQL. I see the benefits, and I understand why teams love it. There are times when it makes perfect sense, such as:

• When you are building highly customizable applications that require retrieving different sets of data for different users.
• When performance optimization is critical, and reducing multiple API calls to one is a game-changer.
• When you have a well-documented API with a strong team that fully understands how to work with GraphQL.

However, in early-stage product development, GraphQL introduces more complexity than it removes. The increased startup cost of development, the reliance on documentation, and the potential for misinterpretation make it a difficult choice for teams that need speed and clarity.

How Product Managers Can Work with GraphQL More Effectively

For product managers who are working with GraphQL, there are ways to mitigate these challenges.

1. Set Clear Expectations on API Documentation

If you are working with a third-party provider, push for detailed documentation before development begins. Request examples of:

• Expected data formats.
• Common API queries.
• Error handling responses.

This will save significant time down the road.

2. Involve Engineering Early

Since GraphQL requires teams to structure queries manually, involve engineers early in the requirements phase. Ensure they have the time to:

• Review the GraphQL schema.
• Identify potential issues before development begins.
• Confirm that what you are asking for is technically feasible.

3. Prototype and Test API Calls Before Finalizing Requirements

With REST, teams often define product requirements first and then see what is possible. With GraphQL, it is better to experiment first. Having a developer test out queries in a GraphQL playground before finalizing the feature scope can help avoid misalignment.

4. Focus on the First 30-60 Days of Feature Needs

If you are launching a new product or integration, focus on what is actually needed in the first 30 to 60 days. GraphQL gives you endless possibilities, but not all of them need to be implemented immediately. Prioritizing what matters will reduce complexity and speed up development.

Final Thoughts: Is GraphQL Right for Every Team?

GraphQL is a powerful tool, but it is not always the right one.

For mature products with well-defined data structures and teams that are comfortable writing complex queries, GraphQL can be a game-changer. But for teams working on early-stage product development, it can slow things down, introduce unnecessary complexity, and create frustrating roadblocks.

As a product manager, my job is to balance technical feasibility with product clarity. And while GraphQL brings incredible flexibility, that flexibility comes at a cost.

At the end of the day, choosing REST or GraphQL is not just a technical decision. It is a product decision, and teams need to consider how it will impact speed, efficiency, and clarity before committing.

About ProductFTW

ProductFTW is a weekly newsletter about product management, with a focus on real-life experiences in startups. We want to help product leaders be successful by giving realistic approaches that aren’t for giant tech companies. We know you don’t have a full-time product designer on each team. We know your software probably hasn’t been used by millions of people worldwide–yet. We’re here to bridge the content gap from building your product and team to scaling it.