REST, GraphQL, gRPC, and webhooks
Choose REST, GraphQL, gRPC, or webhooks by caching, latency, and contract needs.
Protocol comparison matrix
Trade-offs across caching, guardrails, and AI tool mapping.
| Dimension | REST (OpenAPI 3.1) | GraphQL | gRPC (Protobuf) | Webhooks / SSE |
|---|---|---|---|---|
| Primary fit | Public developer APIs, SaaS, CRUD | UI BFFs aggregating multiple entities | Low-latency internal microservices | Async event callbacks and AI streaming |
| Edge caching | Native HTTP (ETag, Cache-Control) | Needs persisted queries + CDN | None (HTTP/2 RPC) | Push / stream only |
| Guardrails | api_validator.py (22 checks) | Persisted queries, depth/cost caps | Strict .proto compatibility + mTLS | HMAC-SHA256 + 5-min replay window |
| AI / MCP tool fit | Direct 1-to-1 OpenAPI to tool mapping | Needs curated query wrappers | Needs REST/gRPC gateway | SSE powers remote MCP servers |