gRPC vs REST — Choosing the Right Protocol

REST (JSON over HTTP/1.1 or HTTP/2):
  Format:       JSON — human-readable, text-based
  Contract:     OpenAPI spec (often generated post-hoc)
  Transport:    HTTP verbs (GET, POST, PUT, DELETE)
  Streaming:    Possible but HTTP-based (SSE, WebSockets separate)
  Browser:      Native fetch/XMLHttpRequest support
  Tooling:      Universal (curl, Postman, browsers)

gRPC (Protobuf over HTTP/2):
  Format:       Binary — compact, fast, not human-readable
  Contract:     .proto file (primary artifact, code-generated)
  Transport:    4 patterns: unary, server streaming, client streaming, bidirectional
  Streaming:    Built-in, first-class feature
  Browser:      Requires gRPC-Web proxy or transcoder
  Tooling:      grpcurl, Postman gRPC, BloomRPC

Benchmark: sending 1,000 CreatePatient requests

REST (JSON):
  Request size:   ~200 bytes JSON
  Response size:  ~180 bytes JSON  
  Latency (avg):  3.2ms
  Throughput:     ~8,000 req/s

gRPC (Protobuf):
  Request size:   ~60 bytes binary (3x smaller)
  Response size:  ~50 bytes binary
  Latency (avg):  1.1ms (3x faster)
  Throughput:     ~25,000 req/s (3x higher)

gRPC advantages:
  ✓ Smaller payloads (Protobuf vs JSON)
  ✓ Binary parsing faster than JSON text parsing
  ✓ HTTP/2 multiplexing (multiple calls on one connection)
  ✓ Header compression (HPACK)

Choose gRPC for:
  ✓ Internal service-to-service communication (no browser)
  ✓ High-throughput data pipelines (device telemetry, observation ingestion)
  ✓ Real-time streaming (vitals monitoring, lab result feeds)
  ✓ Polyglot environments (C#, Java, Go, Python all use same .proto)
  ✓ Strict API contracts with generated client code
  ✓ Latency-sensitive paths (medication dispensing confirmation, alert routing)
  ✓ When you have 10+ RPCs and want type-safe client generation

Choose REST for:
  ✓ Public-facing APIs consumed by browsers, third parties
  ✓ Simple CRUD APIs with no streaming requirements
  ✓ APIs that must be easily explored with curl or Postman
  ✓ APIs consumed by mobile apps (iOS, Android — better REST tooling)
  ✓ Teams new to gRPC where onboarding cost outweighs benefits
  ✓ Simple webhooks and callbacks
  ✓ APIs where human-readable payloads aid debugging

SystemForge Clinical API (production):

  External facing (browsers, mobile apps, third parties):
    REST + JSON → /api/v1/patients, /api/v1/prescriptions

  Internal service communication:
    gRPC → PharmacyService, LabService, NotificationService, BillingService

  Real-time (ward dashboards, vitals monitoring):
    SignalR (WebSocket) → /hubs/clinical

This is not "REST vs gRPC" — it is using the right tool for each context.

// If you need browsers to call gRPC, add gRPC-Web transcoder
// NuGet: Grpc.AspNetCore.Web

app.UseGrpcWeb(new GrpcWebOptions { DefaultEnabled = true });
app.MapGrpcService<ClinicalPatientGrpcService>().EnableGrpcWeb();

// Browser uses fetch API via @grpc/grpc-js or grpc-web package
// Server transcodes gRPC-Web to standard gRPC internally
// Performance: some overhead vs native gRPC, but still better than REST/JSON

REST: API contract is an afterthought (usually)
  Code first → OpenAPI generated from code annotations
  Contract drift is possible (annotations lag implementation)
  Breaking changes detectable via schema diff tools

gRPC: contract is the source of truth
  .proto first → code generated FROM the contract
  Implementation must match the contract exactly
  Breaking changes detectable at compile time (field number changes)
  Proto evolution rules enforce backward compatibility

Is the caller a browser or public API consumer?
  YES → REST
  NO  → consider gRPC

Does the call require streaming?
  YES → gRPC (first-class) or SignalR (WebSocket, better browser support)
  NO  → either, but gRPC if performance matters

Is performance/throughput critical?
  YES, high volume (>1000 req/s) → gRPC
  NO, standard web API → REST is fine

Do you need a strict, versioned contract?
  YES (multiple teams, polyglot clients) → gRPC
  NO (one team, one language) → REST is simpler

Is the team familiar with gRPC?
  YES → gRPC for internal services
  NO  → REST until team is ready (gRPC onboarding cost is real)

gRPC disadvantages:
  ✗ Binary format — not human-readable (debugging requires grpcurl or reflection)
  ✗ Browser support requires gRPC-Web proxy (not native fetch)
  ✗ .proto file management (schema drift between services, shared library needed)
  ✗ Steeper learning curve than REST
  ✗ Less tooling than REST (though improving rapidly)
  ✗ Firewall/proxy issues (some infrastructure does not support HTTP/2 trailers)
  ✗ No native support for browser EventSource / SSE fallback

REST disadvantages:
  ✗ Verbose JSON payloads (larger, slower parsing)
  ✗ No native streaming (requires WebSockets or SSE separately)
  ✗ No code-generated typed clients (requires OpenAPI codegen separately)
  ✗ No formal streaming call semantics