REST vs gRPC vs GraphQL: A Production Decision Guide

@RestController
@RequestMapping("/api/v1")
public class OrderController {
    private final OrderService orderService;
 
    @GetMapping("/orders/{id}")
    public ResponseEntity<OrderResponse> getOrder(
            @PathVariable String id,
            @RequestHeader(value = "If-None-Match", required = false) String ifNoneMatch) {
 
        Order order = orderService.findById(id)
            .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
 
        String etag = "\"" + order.getVersion() + "\"";
 
        // Conditional GET: client already has this version — return 304
        if (etag.equals(ifNoneMatch)) {
            return ResponseEntity.status(HttpStatus.NOT_MODIFIED)
                .eTag(etag).build();
        }
 
        return ResponseEntity.ok()
            .eTag(etag)
            .cacheControl(CacheControl.maxAge(Duration.ofMinutes(5)).mustRevalidate())
            .body(OrderResponse.from(order));
    }
 
    @PostMapping("/orders")
    public ResponseEntity<OrderResponse> createOrder(
            @Valid @RequestBody CreateOrderRequest request,
            @RequestHeader(value = "Idempotency-Key", required = false) String idempotencyKey) {
 
        // Idempotency: same key = return original response, never a duplicate
        if (idempotencyKey != null) {
            Optional<Order> existing = orderService.findByIdempotencyKey(idempotencyKey);
            if (existing.isPresent()) {
                return ResponseEntity.created(buildOrderUri(existing.get().getId()))
                    .body(OrderResponse.from(existing.get()));
            }
        }
 
        Order order = orderService.create(request, idempotencyKey);
        return ResponseEntity.created(buildOrderUri(order.getId()))
            .body(OrderResponse.from(order));
    }
 
    private URI buildOrderUri(String orderId) {
        return UriComponentsBuilder.fromPath("/api/v1/orders/{id}")
            .buildAndExpand(orderId).toUri();
    }
}

// Version is explicit and cacheable
@RestController
@RequestMapping("/api/v1/products")
public class ProductControllerV1 { /* ... */ }
 
@RestController
@RequestMapping("/api/v2/products")
public class ProductControllerV2 { /* ... */ }

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "order 12345 not found"
}

syntax = "proto3";
package commerce.orders.v1;
 
service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  rpc StreamOrderEvents(StreamOrderEventsRequest) returns (stream OrderEvent);
}
 
message Order {
  string id = 1;
  string customer_id = 2;
  repeated LineItem items = 3;
  OrderStatus status = 4;
  double total_usd = 5;
  int64 created_at_ms = 6;
}
 
message LineItem {
  string product_id = 1;
  int32 quantity = 2;
  double unit_price_usd = 3;
}
 
enum OrderStatus {
  PENDING = 0;
  CONFIRMED = 1;
  SHIPPED = 2;
  DELIVERED = 3;
}
 
message GetOrderRequest { string id = 1; }
message CreateOrderRequest {
  string customer_id = 1;
  repeated LineItem items = 2;
  string idempotency_key = 3;
}
message StreamOrderEventsRequest { string order_id = 1; }
message OrderEvent {
  string order_id = 1;
  OrderStatus status = 2;
  int64 occurred_at_ms = 3;
}

func (s *OrderServer) GetOrder(ctx context.Context, req *pb.GetOrderRequest) (*pb.Order, error) {
    if req.GetId() == "" {
        return nil, status.Error(codes.InvalidArgument, "order id required")
    }
 
    row := s.db.QueryRow(ctx,
        `SELECT id, customer_id, status, total_usd, created_at
         FROM orders WHERE id = $1`, req.GetId())
 
    var o pb.Order
    var createdAt time.Time
    var statusStr string
    err := row.Scan(&o.Id, &o.CustomerId, &statusStr, &o.TotalUsd, &createdAt)
    if errors.Is(err, pgx.ErrNoRows) {
        return nil, status.Errorf(codes.NotFound, "order %q not found", req.GetId())
    }
    if err != nil {
        return nil, status.Error(codes.Internal, "fetch failed")
    }
 
    st, ok := pb.OrderStatus_value[statusStr]
    if !ok { // never let a bad row silently become PENDING (the zero value)
        return nil, status.Errorf(codes.Internal, "order %q has unknown status %q", o.Id, statusStr)
    }
    o.Status = pb.OrderStatus(st)
    o.CreatedAtMs = createdAt.UnixMilli()
 
    // Fetch line items
    rows, err := s.db.Query(ctx,
        `SELECT product_id, quantity, unit_price_usd FROM order_items WHERE order_id = $1`,
        o.Id)
    if err != nil {
        return nil, status.Error(codes.Internal, "fetch line items failed")
    }
    defer rows.Close()
 
    for rows.Next() {
        var item pb.LineItem
        if err := rows.Scan(&item.ProductId, &item.Quantity, &item.UnitPriceUsd); err != nil {
            return nil, status.Error(codes.Internal, "scan line item failed")
        }
        o.Items = append(o.Items, &item)
    }
    if err := rows.Err(); err != nil {
        return nil, status.Error(codes.Internal, "line item iteration failed")
    }
 
    return &o, nil
}
 
func (s *OrderServer) StreamOrderEvents(
    req *pb.StreamOrderEventsRequest,
    stream pb.OrderService_StreamOrderEventsServer,
) error {
    ctx := stream.Context()
    ch, unsubscribe := s.events.Subscribe(req.GetOrderId())
    defer unsubscribe()
 
    for {
        select {
        case <-ctx.Done(): // client disconnected or deadline passed
            return status.FromContextError(ctx.Err()).Err()
        case event, ok := <-ch:
            if !ok {
                return nil // publisher closed the subscription
            }
            if err := stream.Send(event); err != nil {
                return err
            }
        }
    }
}

// SAFE: Add new fields — old clients ignore them
message Order {
  string id = 1;
  double total = 2;
  string tracking_id = 4;    // ✅ New field
}
 
// DANGEROUS: Never reuse field numbers
message Order {
  string id = 1;
  // double total = 2;        // ❌ Deleted
  reserved 2;                 // ✅ Prevent reuse
  string currency_total = 5;
}
 
// SAFE: Add new enum values (at the end only)
enum OrderStatus {
  PENDING = 0;
  SHIPPED = 1;
  RETURNED = 2;              // ✅ New value
}

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("listen: %v", err)
    }
 
    creds, err := credentials.NewServerTLSFromFile("server.crt", "server.key")
    if err != nil {
        log.Fatalf("TLS: %v", err)
    }
 
    srv := grpc.NewServer(
        grpc.Creds(creds),
        grpc.ChainUnaryInterceptor(
            tracingInterceptor(),
            loggingInterceptor(logger),
            authInterceptor(tokenVerifier),
            recoveryInterceptor(), // catch panics, return codes.Internal
        ),
    )
 
    orderSrv := &OrderServer{db: pool, events: eventBus}
    pb.RegisterOrderServiceServer(srv, orderSrv)
 
    // Health checking — required for Kubernetes readiness probes
    healthSrv := health.NewServer()
    grpc_health_v1.RegisterHealthServer(srv, healthSrv)
    healthSrv.SetServingStatus(
        "commerce.orders.v1.OrderService",
        grpc_health_v1.HealthCheckResponse_SERVING,
    )
 
    // Graceful shutdown: mark NOT_SERVING before terminating
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, syscall.SIGTERM, syscall.SIGINT)
    go func() {
        <-stop
        healthSrv.SetServingStatus(
            "commerce.orders.v1.OrderService",
            grpc_health_v1.HealthCheckResponse_NOT_SERVING,
        )
        time.Sleep(5 * time.Second) // drain in-flight RPCs from load balancer
        srv.GracefulStop()
    }()
 
    if err := srv.Serve(lis); err != nil {
        log.Fatalf("serve: %v", err)
    }
}

const serviceConfig = `{
  "methodConfig": [{
    "name": [{"service": "commerce.orders.v1.OrderService"}],
    "retryPolicy": {
      "maxAttempts": 3,
      "initialBackoff": "0.1s",
      "maxBackoff": "1s",
      "backoffMultiplier": 2.0,
      "retryableStatusCodes": ["UNAVAILABLE"]
    },
    "timeout": "5s"
  }],
  "retryThrottling": {"maxTokens": 10, "tokenRatio": 0.1}
}`
 
func NewOrderClient(addr string, tlsCfg *tls.Config) (*OrderClient, error) {
    conn, err := grpc.NewClient(addr,
        grpc.WithTransportCredentials(credentials.NewTLS(tlsCfg)),
        grpc.WithDefaultServiceConfig(serviceConfig),
    )
    if err != nil {
        return nil, fmt.Errorf("dial %s: %w", addr, err)
    }
    return &OrderClient{client: pb.NewOrderServiceClient(conn)}, nil
}
 
func (c *OrderClient) GetOrder(ctx context.Context, id string) (*pb.Order, error) {
    // Derive timeout from incoming context — never use context.Background() here
    ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()
 
    return c.client.GetOrder(ctx, &pb.GetOrderRequest{Id: id})
}

type Query {
  order(id: ID!): Order
  product(id: ID!): Product
  products(first: Int = 20, after: String): ProductConnection
}
 
type Mutation {
  createOrder(input: CreateOrderInput!): CreateOrderPayload!
}
 
type Order {
  id: ID!
  status: OrderStatus!
  items: [LineItem!]!
  customer: Customer!
  total: Money!
}
 
type LineItem {
  product: Product!
  quantity: Int!
  unitPrice: Money!
}
 
type Product {
  id: ID!
  name: String!
  description: String
  price: Money!
  thumbnailUrl: String!
  inStock: Boolean!
  relatedProducts(first: Int): [Product!]!
}

# Mobile: exactly 4 fields per product
query CheckoutProducts {
  products(first: 20) {
    edges {
      node {
        name
        price
        thumbnailUrl
        inStock
      }
    }
  }
}
 
# Desktop: more fields, including expensive relatedProducts
query DetailPage($id: ID!) {
  product(id: $id) {
    name
    price
    description
    relatedProducts(first: 5) {
      name
      price
    }
  }
}

package graph
 
import (
    "context"
    "errors"
    "log/slog"
 
    "example.com/shop/graph/model"
    "github.com/graph-gophers/dataloader/v7"
)
 
type Resolver struct {
    productRepo ProductRepository
    orderRepo   OrderRepository
}
 
type DataLoaders struct {
    ProductByID *dataloader.Loader[string, *model.Product]
}
 
type loadersKey struct{}
 
// Request-scoped: middleware stores a fresh set in each request's context.
// The default cache never evicts, so a process-wide loader serves stale rows.
func loadersFor(ctx context.Context) *DataLoaders {
    return ctx.Value(loadersKey{}).(*DataLoaders)
}
 
// Field resolver: runs once per object. DataLoader batches these.
func (r *lineItemResolver) Product(
    ctx context.Context,
    obj *model.LineItem,
) (*model.Product, error) {
    return loadersFor(ctx).ProductByID.Load(ctx, obj.ProductID)()
}
 
// Mutation: validation errors in the payload, infrastructure failures top-level
func (r *mutationResolver) CreateOrder(
    ctx context.Context,
    input model.CreateOrderInput,
) (*model.CreateOrderPayload, error) {
    if len(input.Items) == 0 {
        return &model.CreateOrderPayload{
            Errors: []model.UserError{{Message: "order must contain at least one item"}},
        }, nil
    }
 
    order, err := r.orderRepo.Create(ctx, input)
    if err != nil {
        // Not the client's fault: log the cause, don't leak it in the response
        slog.ErrorContext(ctx, "create order", "err", err)
        return nil, errors.New("order could not be created")
    }
 
    return &model.CreateOrderPayload{Order: order}, nil
}

// Edge handler: still serves REST to partners, calls gRPC internally
func (h *OrderHandler) GetOrder(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()
 
    id := chi.URLParam(r, "id")
 
    // Internal call: now gRPC. External shape: still JSON.
    order, err := h.grpcClient.GetOrder(ctx, &pb.GetOrderRequest{Id: id})
    if err != nil {
        switch status.Code(err) {
        case codes.NotFound:
            writeProblemDetail(w, http.StatusNotFound, "order not found", id)
        case codes.DeadlineExceeded:
            writeProblemDetail(w, http.StatusGatewayTimeout, "upstream timeout", id)
        default:
            writeProblemDetail(w, http.StatusBadGateway, "upstream error", id)
        }
        return
    }
 
    // Translate proto → versioned JSON contract partners depend on
    resp := OrderResponseV1{
        ID:         order.Id,
        CustomerID: order.CustomerId,
        Status:     strings.ToLower(order.Status.String()),
        TotalUSD:   order.TotalUsd,
        CreatedAt:  time.UnixMilli(order.CreatedAtMs).UTC().Format(time.RFC3339),
    }
 
    // Marshal before writing anything: Encode-to-w would fail partway on
    // a bad value (e.g. NaN from a corrupt total_usd) and leave the client
    // with a silent 200 and an empty body.
    body, err := json.Marshal(resp)
    if err != nil {
        slog.ErrorContext(ctx, "marshal order response", "order_id", id, "err", err)
        writeProblemDetail(w, http.StatusInternalServerError, "response encoding failed", id)
        return
    }
 
    w.Header().Set("Content-Type", "application/json")
    w.Header().Set("Cache-Control", "private, max-age=30")
    if _, err := w.Write(body); err != nil {
        // Headers are already sent at this point; all that's left is to record the failure.
        slog.ErrorContext(ctx, "write order response", "order_id", id, "err", err)
    }
}

message Order {
  string id = 1;
  string customer_id = 2;
  repeated LineItem items = 3;
  OrderStatus status = 4;
 
  // Year 1: total in dollars (deprecated, kept for old clients)
  double total_usd = 5 [deprecated = true];
  int64 created_at_ms = 6;
  reserved 7;                           // never reuse: was a removed field
  reserved "legacy_promo_code";         // also block the old name
 
  // Year 2: replaced with structured Money to support multi-currency
  Money total_money = 8;
 
  // Year 2: optional shipping info — old clients ignore unknown fields
  ShippingDetails shipping = 9;
}