Supergraph Routing with GraphOS Router
Learn the basics about router features and deployment types
What is GraphOS Router?
GraphOS Router is the runtime of the GraphOS platform. It executes client operations by planning and executing subgraph queries, then merging them into client responses. It's also the single entry point and gateway to your federated GraphQL API.
Runtime of GraphOS platform
As the runtime of the GraphOS platform, a GraphOS Router gets the supergraph schema—the blueprint of the federated graphs—from the GraphOS control plane. It then executes incoming clients operations based on that schema.
Unlike API gateways that offer capabilities to manage API endpoints, the router isn't based on URLs or REST endpoints. Rather, the router is a GraphQL-native solution for handling client APIs.
Subgraph query planner
Whenever your router receives an incoming GraphQL operation, it needs to figure out how to use your subgraphs to populate data for each of that operation's fields. To do this, the router generates a query plan:
A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. Some of these operations depend on the results of other operations, so the query plan also defines any required ordering for their execution. The router's query planner determines the optimal set of subgraph queries for each client operation, then it merges the subgraph responses into a single response for the client.
You can use the following tools for inspecting query plans:
Use the Explorer IDE to view dynamically calculated example query plans for your operations in its right-hand panel.
Use the Apollo Solutions command line utility for generating a query plan locally.
Entry point to federated GraphQL API
The GraphOS Router is the gateway and entry point to a federated supergraph. Clients send GraphQL operations to your router's public endpoint instead of directly to your APIs.
GraphOS Router deployment types
As the entry point to your supergraph, a GraphOS Router must be able to process the expected load of client operations. The scalability and performance of a router, or a fleet or router instances, can be influenced by their deployment infrastructure.
Cloud-hosted routers
You can choose for Apollo to provision and manage the runtime infrastructure for your routers. Apollo hosts and deploys each instance of router in the cloud. Each cloud-hosted router instance is fully integrated and configurable within GraphOS.
Self-hosted routers
You can choose to manage the runtime infrastructure for your routers by yourself. Using container images of router, you can host and deploy your router instances from your own infrastructure. These self-hosted router instances allow you full control over their deployment.
Common router core
Both cloud-hosted and self-hosted routers are powered by the Apollo Router Core—a high-performance router packaged as a standalone binary.
Router type comparison
Apollo offers the following router options, in increasing order of configurability:
| Router type | Description | Configurability | Plan availability |
|---|---|---|---|
| Shared cloud router | Apollo provisions and manages routers on shared infrastructure. | Basic configurability, including HTTP header rules, CORS settings, and subgraph error inclusion | Serverless** |
| Dedicated cloud router | Apollo provisions and manages routers on dedicated infrastructure that you control and scale. | Highly configurable, including all options for shared cloud routers and additional configurations | Dedicated** |
| Self-hosted router | You host and manage the router on your own infrastructure. | Highly configurable and customizable, including all options for Cloud Dedicated routers and additional customization options. | The Apollo Router Core is available as a free and source-available router. Connecting your self-hosted router to GraphOS requires an Enterprise plan. |
GraphOS Router features
Although powered by the source-available Apollo Router Core binary, GraphOS Routers offer an expanded feature set that isn't available when running the Apollo Router Core without connecting it to GraphOS.
Cloud-hosted routers automatically have access to additional GraphOS Router features, while self-hosted routers must be authenticated with a GraphOS Enterprise license to gain access to these features. Refer to the pricing page to compare GraphOS Router features across plan types.
Next steps
Learn more about Apollo-managed routers in cloud-hosted router
Learn more about deploying router instances in your own infrastructure in self-hosted router
Learn the basics about configuring a router in Configuring a Router
For all available configuration options, go to Router configuration reference docs
To learn more about the intricacies of query plans, see the example graph and query plan in reference docs