REST vs GraphQL Trade-offs

REST in Magento 2

// REST API endpoint
// GET /rest/V1/products/:sku
// POST /rest/V1/carts/mine/items
// PUT /rest/V1/carts/mine/items/:itemId

// Magento REST implementation
class ProductController implements 
    \Magento\Framework\Api\SearchCriteriaInterface
{
    public function get($sku)
    {
        return $this->productRepository->get($sku);
    }
}

GraphQL in Magento 2

# GraphQL query
query {
  products(filter: { sku: { eq: "24-WB04" } }) {
    items {
      name
      sku
      price_range {
        minimum_price {
          regular_price { value currency }
        }
      }
      description { html }
    }
  }
}

Core Difference

REST: Resource-oriented
├── /products/123
├── /orders/456
└── /customers/789

GraphQL: Query-oriented
{
  product(id: 123) { name price }
  order(id: 456) { status items }
}

Network Efficiency

REST (multiple endpoints):
GET /products/123        → 2KB response
GET /products/123/attrs  → 5KB response
GET /products/123/stock  → 1KB response
Total: 3 requests, 8KB

GraphQL (single query):
query { product(id: 123) {
  name price attributes { name value }
  stock { quantity }
}}
Total: 1 request, 6KB

Over-fetching Problem

// REST: Fixed response structure
// GET /products/123 returns ALL fields
{
  "id": 123,
  "name": "Widget",
  "price": 29.99,
  "description": "Long HTML...",  // Not needed
  "categories": [...],            // Not needed
  "related_products": [...]       // Not needed
}

// GraphQL: Request only what you need
query {
  product(id: 123) {
    name
    price_range {
      minimum_price { regular_price { value } }
    }
  }
}

Under-fetching (N+1 Problem)

REST: Multiple round trips needed
GET /orders/456           → order with customer_id
GET /customers/789        → customer details
GET /addresses/101        → shipping address

GraphQL: Single query with resolution
query {
  order(id: 456) {
    customer { name email }
    shipping_address { city zip }
  }
}

REST Caching

// HTTP caching headers
// GET /rest/V1/products/123
// Cache-Control: max-age=3600
// ETag: "abc123"
// Last-Modified: Wed, 01 Jan 2025 00:00:00 GMT

// Varnish cache keys
cache_key = http_host + request_uri
// Easy to cache at HTTP level
// CDN-friendly

// Redis cache for REST
$cacheKey = 'rest_product_' . $sku;
$this->cache->save($response, $cacheKey, [], 3600);

GraphQL Caching Challenges

# Different queries, same data
query { product(id: 123) { name price } }
query { product(id: 123) { name description } }

# Cache key = entire query string
# Same product cached multiple times

# Solution: Normalized cache
{
  "Product:123": {
    "name": "Widget",
    "price": 29.99,
    "description": "Long HTML..."
  }
}

Cache Strategy Comparison

Implementation Complexity

// REST: Simple, well-understood
// routes/api.php
Route::get('/products/{id}', 'ProductController@show');
Route::post('/orders', 'OrderController@store');

// GraphQL: Schema design required
type Product {
  id: ID!
  name: String!
  sku: String!
  price: Money!
  stock: StockLevel
}

type Query {
  product(id: ID!): Product
  products(filter: ProductFilterInput): ProductConnection
}

Client Complexity

// REST client
const product = await fetch('/api/products/123');
const data = await product.json();

// GraphQL client (Apollo)
const { data } = await client.query({
  query: GET_PRODUCT,
  variables: { id: 123 }
});

// GraphQL requires schema knowledge
// REST is self-documenting via endpoints

Maintenance Overhead

REST:
+ Endpoints are self-contained
+ Easy to version (v1, v2)
+ Simple to debug (URL-based)
- Many endpoints to maintain
- Versioning creates duplication

GraphQL:
+ Single endpoint
+ Schema evolution without versioning
+ Strong typing
- Schema complexity grows
- Resolver performance issues
- Harder to debug