GraphQL vs REST APIs

# CHAPTER 3

GraphQL vs REST APIs #

1. Introduction #

2. Learning Objectives #

• Identify the core limitations of traditional REST APIs.

• Define and explain "Over-fetching" and "Under-fetching."

• Compare how endpoints are structured in REST vs. GraphQL.

• Understand how GraphQL provides flexible, client-driven queries.

• Decide when to use REST and when to use GraphQL.

3. Beginner-Friendly Explanation #

Using GraphQL is like packing your own bag. You look at a master list of items (the Schema) and say, "I want two shirts, one toothbrush, and socks." The server packs exactly those items into a single bag and hands it to you. It is perfectly tailored to your needs.

4. Real-World Examples #

• The Blog Scenario (REST): To display a blog post with its author's name and top 3 comments, a client might have to make 3 separate HTTP requests:

1. 1. /posts/1 (Gets the post)

1. 2. /users/42 (Gets the author details)

1. 3. /posts/1/comments (Gets all comments)

• The Blog Scenario (GraphQL): The client makes exactly 1 HTTP request to /graphql, asking specifically for the post content, the author's name, and the first 3 comments.

5. Detailed Code Examples #

REST Example (PHP / cURL making multiple requests):

<?php
// Request 1: Get user
$user = file_get_contents(&#039;https://api.example.com/users/1');
// Request 2: Get user's posts
$posts = file_get_contents(&#039;https://api.example.com/users/1/posts');
?>

GraphQL Example (PHP making a single request):

<?php
$query = json_encode([
    &#039;query' => '
        query {
            user(id: 1) {
                name
                posts {
                    title
                }
            }
        }
    &#039;
]);

// Single request fetches everything perfectly formatted
$response = file_get_contents(&#039;https://api.example.com/graphql', false, stream_context_create([
    &#039;http' => [
        &#039;method' => 'POST',
        &#039;header' => 'Content-Type: application/json',
        &#039;content' => $query
    ]
]));
?>

6. Query Examples (GraphQL's Solution) #

query {
  author(id: "5") {
    name
    email
    recentPosts(limit: 2) {
      title
      date
    }
  }
}

7. Mutation Examples #

mutation {
  updateUserEmail(id: "5", newEmail: "new@example.com") {
    id
    email
  }
}

8. Schema Examples #

type Author {
  id: ID!
  name: String
  recentPosts: [Post]
}

type Post {
  title: String
  date: String
}

9. Best Practices #

• Don't abandon REST completely: REST is still excellent for simple APIs, file uploads, and microservice-to-microservice communication. Choose the right tool for the job.

• Use GraphQL for Data-Heavy UIs: If you are building a complex React, Vue, or mobile application with diverse data needs, GraphQL is vastly superior.

• Monitor Payload Size: While GraphQL prevents over-fetching fields, clients can accidentally ask for deeply nested lists (e.g., users -> friends -> friends -> friends), causing server strain.

10. Common Mistakes #

• Assuming GraphQL is universally faster: GraphQL reduces network requests, which helps on mobile connections, but calculating complex queries on the server requires processing power. Badly written GraphQL can actually be slower.

• Duplicating logic: Don't put business logic inside your GraphQL layer. It should merely route the request to your existing backend PHP services.

11. Mini Exercises #

1. 1. Define Over-fetching in one sentence.

1. 2. Define Under-fetching in one sentence.

1. 3. Compare the number of URLs (endpoints) used in a typical REST API versus a typical GraphQL API.

12. Coding Challenges #

• How would a REST API respond to /movies?

• Write the GraphQL query to fetch exactly what you need.

13. MCQs with Answers #

14. Interview Questions #

• Q: Compare and contrast GraphQL and REST. What problem does GraphQL solve?

• Q: Explain "N+1 Problem" in the context of APIs (Under-fetching).

• Q: In what scenario would you choose REST over GraphQL?

15. FAQs #

Q: Is GraphQL harder to cache than REST? A: Yes. Because REST uses unique URLs for every resource, standard HTTP caching (like Varnish or CDN) works perfectly. Since GraphQL uses a single endpoint with dynamic POST bodies, standard HTTP caching is much more difficult, requiring specialized clients like Apollo.

16. Summary #

17. Next Chapter Recommendation #