Using GraphQL Gateway
1. Understanding Gateway Pattern
| Responsibility | Detail |
|---|---|
| Schema composition | Build supergraph from subgraphs |
| Query planning | Decompose into subgraph operations |
| Execution | Issue, await, merge subgraph results |
| Entry point | Single endpoint for clients |
2. Setting Up Apollo Gateway
Example: Apollo Router (recommended)
# router.yaml
supergraph:
listen: 0.0.0.0:4000
introspection: false
override_subgraph_url:
users: http://users:4001/graphql
orders: http://orders:4002/graphql
traffic_shaping:
router: { timeout: 30s }3. Configuring Supergraph Schema
| Source | Detail |
|---|---|
| Static SDL | Pre-composed supergraph.graphql |
| Apollo Studio | Managed federation; schema published per subgraph |
| IntrospectAndCompose | Runtime composition (legacy gateway) |
4. Implementing Query Planning
| Phase | Detail |
|---|---|
| Parse | Standard parse |
| Plan | Build minimal fetch graph across subgraphs |
| Execute | Run fetches respecting dependencies |
| Merge | Stitch responses by entity keys |
5. Handling Service Health
| Mechanism | Detail |
|---|---|
| Health checks | GET /.well-known/apollo/server-health |
| Circuit breaker | Skip failing subgraph briefly |
| Schema reload | Detect subgraph schema updates |
6. Routing Requests
| Strategy | Detail |
|---|---|
| DNS / service mesh | Standard k8s routing |
| Header propagation | Forward auth, tracing, locale |
| Per-subgraph TLS | mTLS within mesh |
7. Implementing Custom Resolvers
| Use | Mechanism |
|---|---|
| Gateway-only fields | Resolver added at gateway |
| Cross-subgraph aggregation | Multiple delegations + merge |
| Apollo Router coprocessors / Rhai | Custom logic in router |
8. Managing Service Updates
| Practice | Detail |
|---|---|
| Schema check before deploy | rover subgraph check |
| Backward-compatible changes | Add fields/types, deprecate old |
| Coordinated mutations | Add new field then migrate clients then remove |
9. Handling Partial Failures
| Behavior | Detail |
|---|---|
| Subgraph errors | Returned in errors[] with subgraph in extensions |
| Nullable propagation | Nullable parents protect rest of result |
| Timeouts | Per-subgraph timeout to prevent cascade |
10. Monitoring Gateway Performance
| Metric | Detail |
|---|---|
| Plan time | Query planning duration |
| Per-subgraph latency | Slowest dependency |
| Cache hit rate | Plan cache, response cache |
| Error rate by subgraph | Isolate failures |