Choosing the Surface
REST and GraphQL solve different problems and frequently coexist. REST fits resource-oriented operations, benefits from mature HTTP caching, and is straightforward to secure at the edge. GraphQL fits aggregation across many backends and client-driven field selection, at the cost of losing HTTP caching semantics and gaining a query-complexity attack surface.
In enterprise portals, a common and defensible split is GraphQL for the composed read surface that the interface consumes, and REST for machine-to-machine integration, webhooks, and bulk operations where partners expect conventional HTTP semantics.
Designing Contracts That Can Evolve
Availability includes not breaking clients. Additive evolution — new optional fields, new endpoints, deprecation windows with telemetry showing actual usage — keeps consumers working. Breaking changes belong behind a version boundary with a published sunset date.
- Use cursor pagination; offset pagination degrades badly on large data sets.
- Require idempotency keys on all non-idempotent operations.
- Return structured, machine-readable errors with stable codes.
- Enforce query depth and complexity limits on every GraphQL endpoint.
Isolation and Degradation
High availability comes from limiting blast radius. Bulkheads give each downstream dependency its own connection pool and concurrency budget, so one slow system cannot exhaust shared resources. Circuit breakers stop calls to a failing dependency and allow the API to answer with partial data rather than timing out. Per-tenant rate limiting prevents one client's batch job from degrading the portal for everyone else.
GraphQL is particularly well suited to partial success: returning available fields alongside typed errors for the ones that failed keeps the portal useful during a partial outage, where a REST endpoint would return a single 503.
Operating the Surface
Health checks should distinguish liveness from readiness so deployments drain cleanly. Every request should carry a trace identifier through every downstream hop. Service level objectives belong on p99 latency and error rate per operation, not on aggregate averages that hide the failing endpoint. Load tests should model realistic query shapes — for GraphQL, the expensive nested queries clients actually send, not a trivial single-field request.