Migrate Use Case Traffic
Safely move client calls to your production graph
This guide walks your team through migrating active client use cases from legacy endpoints to the new supergraph. You’ll learn how to plan your migration, execute the transition, verify key workflows, and set up monitoring for rapid response to client issues.
Prerequisites
Supergraph deployed and validated in production
All production subgraph endpoints confirmed available
The router is live and reachable from production clients
By the end of the milestone, you’ll have:
Target clients switched from legacy endpoints to the supergraph
Core use case flows tested and validated in production
Steps to complete
1. Choose your migration approach based on your risk tolerance:
Big Bang: Migrate all traffic at once (fastest, highest risk)
Gradual: Migrate use cases incrementally (safer, longer timeline)
Canary: Migrate small percentage first (balanced approach)
2. Confirm readiness and plan migration
Review supergraph functionality with client teams
Ensure all supported queries/mutations are exposed and tested
Validate authentication and authorization flows
Communicate migration window to stakeholders and set expectations for possible issues and recovery steps
Assign clear points of contact for migration support
Establish communication channels for status updates and issue reporting
3. Redirect client requests
Update client configuration to use the supergraph endpoint, queries, mutations, and subscriptions
If possible, use feature flags to redirect the requests
4. Validate core workflows in production
Execute end-to-end tests for migrated workflows
Monitor for errors, performance regressions, or unexpected results
Ask client teams to manually test highest-priority user journeys
5. Monitor live traffic and alerts
Key metrics to track:
Track key performance and reliability indicators (latency, error rates, throughput) in real time using your observability stack.
Review router and subgraph logs for anomalies or edge-case failures.
6. Troubleshoot and rollback if needed
Document issues and remediation steps in a shared channel.
If severe issues occur, revert client traffic to the legacy endpoints using preconfigured rollback mechanisms.
Communicate status and action items transparently with all affected teams.