GraphQL vs REST — When to Choose Each

# --- Scenario: a mobile screen shows a user, their last 5 orders,
#     each with its line items and the product name/thumbnail. ---

# ============ REST (3+ round trips, over-fetch per call) =====================
#   GET /users/42                              -> User JSON with 40 fields
#   GET /users/42/orders?limit=5               -> Array of 5 Order JSONs
#   GET /orders/{id}/items  (x5)               -> 5 item arrays
#   GET /products/{sku}     (x N items)        -> N product JSONs
# Many sequential/parallel requests; clients stitch on-device.

# ============ GraphQL (1 query, exactly what the UI needs) ===================
query OrderHistoryScreen($userId: ID!) {
  user(id: $userId) {
    id
    displayName
    avatarUrl
    orders(last: 5) {
      id
      placedAt
      total { amount currency }
      items {
        quantity
        product {
          sku
          name
          thumbnailUrl
        }
      }
    }
  }
}

# One round-trip; the server walks the graph, batching via DataLoader.
# The mobile client declares the exact field set needed for this screen.

# ============ gRPC (typed RPC, strong perf, not browser-native) ==============
# user_service.proto
syntax = "proto3";
package acme.user.v1;

service UserService {
  rpc GetUserWithOrders (GetUserWithOrdersRequest)
      returns (GetUserWithOrdersResponse);
}

message GetUserWithOrdersRequest { string user_id = 1; int32 last = 2; }

message GetUserWithOrdersResponse {
  User user = 1;
  repeated Order orders = 2;
}

# Fastest on the wire (protobuf + HTTP/2 multiplexing); best for service-to-service.
# Needs gRPC-Web + a proxy for browsers; tooling cost higher than REST.

# Spring-side resolver sketch for the GraphQL version:

@Controller
class OrderHistoryResolvers {

    @QueryMapping
    User user(@Argument String id) { return users.find(id); }

    @SchemaMapping(typeName = "User", field = "orders")
    List<Order> orders(User user, @Argument int last) {
        return orderService.lastN(user.id(), last);
    }

    // Batched resolver for Product to avoid N+1 on items.product
    @BatchMapping
    Map<OrderItem, Product> product(List<OrderItem> items) {
        List<String> skus = items.stream().map(OrderItem::sku).toList();
        Map<String, Product> bySku = productService.getAll(skus);
        return items.stream().collect(Collectors.toMap(i -> i, i -> bySku.get(i.sku())));
    }
}