HyperRoute

Migrating from Apollo Router

HyperRoute is a drop-in replacement for Apollo Router. It uses the same supergraph SDL format, same federation directives, and same OTLP/Prometheus observability protocols. The main changes are configuration key names and a few architectural differences.

Config Mapping

Apollo RouterHyperRouteNotes
supergraph.pathschemaSchema SDL path
homepage.enabledAlways availableBuilt-in playground at /graphql GET
sandbox.enabledsecurity.enable_introspectionIntrospection toggle
telemetry.exporters.tracing.otlpobservability.tracingSame OTLP protocol
telemetry.exporters.metrics.prometheusobservability.metricsSame Prometheus format
limits.max_depthsecurity.max_query_depthSame semantics
rhai scriptsPlugins / CoprocessorsMore powerful
coprocessorcoprocessorsSame HTTP protocol
--hot-reloadBuilt-in alwaysNo flag needed

Migration Steps

1. Install HyperRoute

Install alongside Apollo Router for a gradual migration:

curl -fsSL https://install.hyperroute.dev | sh

2. Convert Configuration

Apollo Router (router.yaml):

supergraph:
  path: ./supergraph.graphql

sandbox:
  enabled: true

limits:
  max_depth: 15

telemetry:
  exporters:
    tracing:
      otlp:
        endpoint: http://tempo:4317
    metrics:
      prometheus:
        enabled: true
        listen: 0.0.0.0:9091

HyperRoute (hyperroute.yaml):

schema: ./supergraph.graphql

security:
  enable_introspection: true
  max_query_depth: 15

observability:
  tracing:
    enabled: true
    endpoint: http://tempo:4317
  metrics:
    enabled: true
    path: /metrics

3. Test with Existing Supergraph

HyperRoute uses the same supergraph SDL format produced by Apollo's rover supergraph compose:

routerd serve --schema supergraph.graphql

Your existing supergraph file works without changes.

4. Verify Metrics

Metric names differ but concepts are the same:

Apollo Router MetricHyperRoute Metric
apollo_router_http_requests_totalhyperroute_requests_total
apollo_router_http_request_duration_secondshyperroute_request_duration_seconds
apollo_router_cache_hit_counthyperroute_cache_hits_total

Update your Grafana dashboards and Prometheus alerting rules accordingly.

5. Switch Traffic

Once verified, update your load balancer or ingress to point to HyperRoute:

# If using Kubernetes, update the service selector
kubectl set image deployment/router router=hyperroute/routerd:latest

6. Remove Apollo Router

Once traffic is fully switched and verified:

# Remove Apollo Router binary/image
# Update CI/CD pipelines
# Remove Apollo Router configuration files

Key Differences

What's Different

FeatureApollo RouterHyperRoute
Schema updatesPolling from registryPush-based (bundles/snapshots)
SecurityBasic (depth limits)Full pipeline (injection detection, adaptive rate limiting, PII masking)
Multi-tenantEnterprise licenseFree, built-in
REST/gRPC subgraphsConnectors plugin (enterprise)Native, free
ScriptingRhaiPlugins + Coprocessors
LicenseELv2 (restrictive)Free
Hot reload--hot-reload flagAlways on

What's the Same

  • ✅ Federation directives (@key, @external, @requires, @provides, @shareable, @override)
  • ✅ Supergraph SDL format
  • ✅ OTLP tracing protocol
  • ✅ Prometheus metrics format
  • ✅ Coprocessor HTTP protocol
  • ✅ GraphQL subscription support

Common Gotchas

  1. No schema registry polling — HyperRoute uses push-based updates. Use the control plane API or file watching instead of polling a registry.

  2. Rhai scripts — Convert Rhai scripts to plugins or coprocessors. Coprocessors are more powerful (any language, external service) and plugins are simpler for common transformations.

  3. Metric names — Update Grafana dashboards. The metric concepts are identical but names use the hyperroute_ prefix instead of apollo_router_.

  4. Hot reload is always on — No need for --hot-reload flag. HyperRoute watches the config file by default.

Next Steps