Why We Switched From REST to GraphQL for Our SaaS Architecture

Last year we migrated our core SaaS APIs from REST to GraphQL. The decision wasn't taken lightly — we had dozens of clients depending on our REST endpoints, and the team was rightfully nervous about breaking changes. Here's what we learned, what broke, and why we'd do it again.

Why we considered GraphQL

Our REST API had grown into a maze of nested resources and over-fetched responses. Mobile clients were pulling entire object graphs when they only needed a few fields; dashboard users were making five or six round-trips to build a single view. We needed a way to let clients ask for exactly what they needed in one request. GraphQL's query language and single endpoint made that possible.

What we did

We introduced a GraphQL layer in front of our existing services and ran it in parallel with REST for six months. We used schema stitching to compose domains (users, billing, usage) and added persisted queries for security. Caching and N+1 prevention required careful use of DataLoader; we invested in tooling and codegen so frontend and mobile could type-check their queries.

What broke (and how we fixed it)

A few legacy clients assumed REST-only behaviour and had to be updated. We also hit performance issues on deeply nested queries until we added query depth limits and complexity analysis. Once those were in place, we deprecated the old REST routes and moved everyone to GraphQL. The result: fewer round-trips, happier frontend and mobile teams, and a single source of truth for our API contract.