GraphQL vs REST

Welcome to GraphQL versus REST. In this talk, we'll explore both API paradigms and help you choose the right one for your next project.

Let's start with REST, the resource-based architecture that's been the standard for decades. REST organizes your API around resources — users, posts, comments — each with its own unique endpoint.

Here's how a typical REST flow works. The client makes a GET request to fetch a user by I-D. The server responds with the full user object. Then the client needs that user's posts, so it makes another request. And if it also needs followers, that's a third request. Notice that the server returns everything it has, regardless of what the client actually needs.

Looking at typical REST endpoints, you can see the pattern. Each resource type gets its own base path — users, posts, comments. You use HTTP verbs like GET, POST, PUT, DELETE to describe the action. And you use path parameters and nesting to describe related resources. This is intuitive and predictable.

Now let's shift gears to GraphQL, which takes a fundamentally different approach. Instead of multiple endpoints per resource, GraphQL uses a single endpoint and lets the client specify exactly what data it needs.

Here's the GraphQL equivalent. The client sends a single POST request to a graphql endpoint. Inside that request is a query that describes exactly what data it needs — the user's name and their posts' titles. The server responds with that exact shape, nothing more, nothing less. One request, one response, everything the client needs.

GraphQL uses a schema to define your API. You declare types like User and Post, specify required fields with exclamation marks, and establish relationships between types. This becomes the contract between client and server. The schema is fully typed, introspectable, and self-documenting.

Let's talk about one of REST's biggest pain points: over-fetching. This happens when the server returns way more data than the client actually needs.

Looking at this REST response, the server is sending back a user's I-D, name, email, avatar, bio, phone, address, timestamps, and preferences. But what if your mobile app only needs the name and email? You're still downloading all that extra data, wasting bandwidth and processing power.

With GraphQL, you write a query asking for just the fields you need — name and email. The response contains exactly those two fields, nothing else. The server never sends data you don't ask for.

Another REST headache is under-fetching, which leads to the N-plus-one problem. This happens when you need related data, forcing multiple round-trips to the server.

Here's a REST scenario. You fetch a user and get back their post I-Ds. But the response doesn't include the post details, so you make a second request to get the first post. That post has comment I-Ds, so you make a third request to get those comments. For a dashboard showing five posts with three comments each, you'd need fifteen requests. That's the N-plus-one problem.

With GraphQL, you write a single query that expresses all your nested data needs. User, their posts, each post's comments, and each comment's author. One request goes to the server. One response comes back with exactly that shape. No round-tripping, no guessing what fields you'll need next.

Now let's compare REST and GraphQL side by side across multiple dimensions.

On the left, you see typical REST code. Multiple endpoints, the server decides what comes back in the response, and you handle versioning by putting slash-v-one or slash-v-two in the U-R-L. On the right, GraphQL has a single endpoint, the client describes its exact data needs in the query, and versioning is handled by schema evolution instead of U-R-L changes.

The table shows key differences. REST uses multiple endpoints per resource, the server controls the response shape, it has native HTTP caching, and errors come back as HTTP status codes. GraphQL uses a single graphql endpoint, the client shapes the response, caching requires normalized strategies, and errors always return 200 with error details in the body. REST uses U-R-L-based versioning like slash-v-one and slash-v-two. GraphQL evolves the schema without versions.

More dimensions. REST has native file upload support with multipart forms. GraphQL requires workarounds for file uploads. REST tools include Postman and curl. GraphQL has GraphiQL and Apollo DevTools. REST has a low learning curve for anyone familiar with H-T-T-P. GraphQL has a moderate curve — you need to understand the schema definition language and resolvers. REST handles real-time via Server-Sent Events or WebSockets. GraphQL has subscriptions built into the spec. REST requires optional tooling for type safety. GraphQL has intrinsic type safety because the schema is mandatory.

One of GraphQL's superpowers is built-in type safety. The schema isn't optional — it's the foundation of the entire system.

Looking at this schema, we have a createPost mutation that takes a CreatePostInput. That input type defines exactly what fields are required — title and body are mandatory, tags are optional. The return type is a Post. Every field, every type, everything is declared upfront.

Because the schema is so explicit, tools can auto-generate TypeScript types. Look at the CreatePostInput interface — it's generated directly from the schema. And the mutation return type, the CreatePostMutation, is also generated with full typing for nested fields. Your frontend code gets compile-time safety automatically.

So when should you choose one over the other? Let's break down the strengths of each.

REST shines for simple CRUD operations, public-facing A-P-Is, and scenarios where HTTP caching is critical. It's great when you're doing lots of file uploads or downloads, or when your team is new to A-P-I design and needs something straightforward. {{step}}GraphQL shines when you have complex, nested data needs, multiple client platforms with different requirements, a rapidly evolving frontend that needs flexibility, real-time subscriptions, or when strict type safety is non-negotiable. {{step}}

Both have common pitfalls. {{step}}With REST, over-fetching and under-fetching waste bandwidth and create request waterfalls. U-R-L-based versioning creates maintenance burden as your A-P-I grows. And tight coupling to backend models makes refactoring painful. {{step}}With GraphQL, caching strategies get complex because responses don't align with H-T-T-P cache semantics. N-plus-one queries on the server are a real danger if resolvers aren't optimized. Error handling doesn't follow H-T-T-P conventions, which confuses some developers. And the learning curve is steeper for teams new to schema-driven design. {{step}}

Let's look at how the industry is actually using these technologies.

The numbers tell an interesting story. As of 2025, 90 percent of A-P-Is still use REST — it remains the default. But GraphQL adoption has grown dramatically, from 14 percent in 2021 to 38 percent today. GitHub's GraphQL A-P-I has 47,000 daily users. And Shopify processes 200 billion GraphQL queries per day. GraphQL is no longer experimental — it's powering production systems at massive scale.

Let's look at real examples. {{step}}GitHub migrated from REST version three to GraphQL version four. REST is still available for backward compatibility, but GraphQL enables precise data fetching for integrations and reduced the A-P-I surface area. {{step}}Shopify went GraphQL-first in 2018. It powers the Storefront A-P-I, Admin A-P-I, and partner integrations. They handle 200 billion queries per day and built custom frontend renderers on top of the GraphQL schema. {{step}}Netflix and Twitter use GraphQL federation internally for microservice composition, while keeping REST for public A-P-Is. Federation stitches hundreds of services into one logical graph, reducing coordination overhead between frontend and backend teams. {{step}}

Making the right choice requires understanding your specific context.

Here's the key: choose REST if your A-P-I is resource-oriented, cache-heavy, or public-facing. Choose GraphQL if you have diverse clients, complex data relationships, or need maximum frontend flexibility. Many teams use both — REST at the edge for external partners and developers, GraphQL internally for product teams. Neither is universally better; context matters.

Let's work through some real scenarios. {{step}}For a mobile app, GraphQL wins because mobile needs minimal payloads and single-request loading to minimize latency on cellular networks. {{step}}For a public A-P-I, REST wins because external developers expect standard H-T-T-P semantics, status codes, and cacheable endpoints. {{step}}For microservices, use both — GraphQL federation as a gateway layer to stitch services together, and REST or gRPC for internal service-to-service communication. {{step}}

Let's wrap up. REST excels at simple CRUD, H-T-T-P caching, and public A-P-Is — it remains the default for most backends. GraphQL eliminates over-fetching and under-fetching by letting clients specify exact data needs. Type safety is intrinsic to GraphQL's schema-first design, enabling code generation and compile-time validation. And most importantly, choose based on your use case — many production systems successfully use REST and GraphQL together.