Docs
Launch GraphOS Studio

Subgraphs

In a federated supergraph


Every federated includes one or more subgraphs. Each is a separate service that's responsible for a different portion of your 's available data.

Here's a basic that includes two (Users and Products):

Supergraph
Router
Users
subgraph
Products
subgraph
Clients

You can implement different using completely different programming languages and libraries!

Choosing a subgraph library

Every in your should use a subgraph-compatible GraphQL server library. These are libraries that adhere to the specification, which ensures that your can take full advantage of federation features like entities.

See federation-compatible subgraph libraries.

After you select a library, consult its documentation to learn how to configure it to run as a subgraph.

If you're using Apollo Server as your subgraph library, see Implementing a subgraph with Apollo Server.

Securing your subgraphs

Implement any necessary firewall rules, access control lists, or other security measures in your environment to ensure that only your supergraph's router can access your individual .

Clients should never query a subgraph directly! Instead, clients should always your , which resolves those queries by communicating with your .

There are many reasons for this:

  • libraries automatically add powerful fields to your schema that clients should not have access to.
    • The uses these to cross boundaries while resolving complex .
  • Providing a single endpoint for your entire reduces its overall attack surface.

In addition to the above security concerns, a significant benefit of any API is that clients only need to interact with one endpoint. This definitely holds true for a , especially one with tens or even hundreds of !

For more information on securing your with a , see this article.

Disabling CORS

We recommend that do not enable CORS (or at least, do not use the wildcard access-control-allow-origin: * header). This prevents attackers from exploiting a user's browser to access a directly.

For , you need to disable the default wildcard CORS policy (this policy is appropriate for many monolithic public API servers, but not for ). For details, see the Apollo Server CORS documentation.

Subgraph-specific fields

-compatible server libraries automatically add some federation-specific definitions to your . In addition to definitions like @key, the most useful of these definitions for debugging are two of the Query type: _service and _entities:

type Query {
# ...your field definitions...
# Added automatically
_service: _Service!
_entities(representations: [_Any!]!): [_Entity]!
}

Query._entities

Learn about entities if you haven't yet.

This takes a list of entity representations and returns a list of corresponding entities.

Whenever one erences another 's , it uses an entity representation to do so. An representation is an object that includes only the 's __typename and the in the 's @key.

_entities(representations: [_Any!]!): [_Entity]!
  • The _Any type is a special that enables you to provide representations of any valid shape.
  • The _Entity type is a generated union type that includes every defined in your 's schema.

You can this like so, providing a value for the $representations as shown:

Query
query ($representations: [_Any!]!) {
_entities(representations: $representations) {
... on User {
id
username
}
}
}
Variable
{
"representations": [
{
"__typename": "User",
"id": "5"
}
]
}

Using in tests and debugging

If you're writing integration tests for your , you can test the return value of the _entities for various representations that your other use.

If you're developing your in your local environment, you can mock the return value of the _entities for your other so you don't have to connect those subgraphs to their respective data stores.

Query._service

This returns a _Service object with one of its own: sdl. You can it like so:

query GetSubgraphSchema {
_service {
sdl
}
}

The sdl returns your 's schema as an string. This field has a couple of important differences from a standard introspection query that a tool like uses:

  • Unlike , the sdl is not disabled by default in production environments (this is safe if you properly secure your subgraph).
  • Unlike , the sdl 's returned string includes federation-specific like @key.
Previous
Working with subgraphs
Next
Supported subgraph libraries
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company