Rest_graphql

Chapter 17: REST vs GraphQL

Choosing the Right API Paradigm

---

17.1 REST Overview

REST (Representational State Transfer) is an architectural style that uses HTTP methods and standard status codes for communication.

    REST API Structure
    ==================

    GET /users/123
    GET /users/123/orders
    POST /users
    PUT /users/123

    Response:
    {
      "id": 123,
      "name": "John",
      "email": "john@example.com"
    }

REST Characteristics

Characteristic	Description
Resources	Nouns (users, orders)
HTTP Methods	GET, POST, PUT, DELETE
Stateless	Each request independent
Standard Status	200, 201, 404, 500

---

17.2 GraphQL Overview

GraphQL is a query language for APIs that allows clients to request exactly the data they need.

    GraphQL Query
    =============

    Query:
    ------
    query {
      user(id: "123") {
        name
        email
        orders {
          id
          total
        }
      }
    }

    Response:
    ---------
    {
      "data": {
        "user": {
          "name": "John",
          "email": "john@example.com",
          "orders": [
            { "id": "1", "total": 100 },
            { "id": "2", "total": 50 }
          ]
        }
      }
    }

GraphQL Characteristics

Characteristic	Description
Query Language	Client specifies fields
Single Endpoint	/graphql
Typed Schema	Strongly typed
Client-driven	Request what you need

---

17.3 Comparison

REST vs GraphQL

Aspect	REST	GraphQL
Data fetching	Multiple endpoints	Single request
Over-fetching	Gets extra data	Exact data needed
Under-fetching	Needs multiple calls	One request
Caching	HTTP caching	Custom caching
Learning curve	Lower	Higher
Tooling	Mature	Growing

---

17.4 Data Fetching Comparison

REST: Multiple Requests

    REST: Fetching User with Orders
    =================================

    Request 1: GET /users/123
    Response: { id, name, email }

    Request 2: GET /users/123/orders
    Response: [ { id, total }, ... ]

    Total: 2 requests

    Problem: What if you need nested data?
    Solution: Create custom endpoint /users/123/with-orders

    But then: Over-fetching if you just need user

GraphQL: Single Request

    GraphQL: Single Request
    ======================

    query {
      user(id: "123") {
        name
        orders {
          total
        }
      }
    }

    Single request!

    GraphQL decides what data to fetch based on query
    Single backend query covers everything

---

17.5 When to Use REST

Ideal for REST

Scenario	Why
Simple resources	CRUD operations
Public APIs	Standard, well understood
Caching important	HTTP caching works well
Microservices	Clear boundaries
Team experience	More familiar

---

17.6 When to Use GraphQL

Ideal for GraphQL

Scenario	Why
Mobile apps	Bandwidth efficient
Complex data	Multiple nested resources
Rapid iteration	Change query without backend
Multiple clients	Web, mobile, TV
Aggregations	Combine data from sources

---

17.7 Real-World Examples

Companies Using Each

REST	GraphQL
Amazon	Facebook
eBay	GitHub
Stripe	Shopify
Twitter	Airbnb

---

17.8 Hybrid Approach

Using Both

    Hybrid Architecture
    ===================

    +--------------------------------------------------+
    |                   API Gateway                    |
    +--------------------------------------------------+
                    |              |
                    v              v
            +-----------+    +-----------+
            |   REST    |    | GraphQL   |
            |   API     |    |   API      |
            +-----------+    +-----------+

    Use REST for:
    - Simple CRUD
    - Public APIs
    - High cacheability

    Use GraphQL for:
    - Complex queries
    - Aggregations
    - Client-specific needs

---

Summary

Key comparison points:

1. REST - Multiple endpoints, predictable, HTTP caching
2. GraphQL - Flexible queries, single endpoint, exact data
3. REST better for - Simple, public, cached APIs
4. GraphQL better for - Complex data, mobile, rapid dev
5. Can use both - Different use cases, same backend

---

Next: Chapter 18: Authentication & Authorization