Apollo Federation

Apollo Federation is a GraphQL architecture for combining multiple GraphQL services, or subgraphs, into a single supergraph. You can read more in the official documentation.

To see a complete example of federation, check out the federation example.

Enabling federation support

async-graphql supports all the functionality of Apollo Federation v2. Support will be enabled automatically if any #[graphql(entity)] resolvers are found in the schema. To enable it manually, use the enable_federation method on the SchemaBuilder.

extern crate async_graphql;
use async_graphql::*;
struct Query;
#[Object]
impl Query {
   async fn hello(&self) -> String { "Hello".to_string() }
}
fn main() {
  let schema = Schema::build(Query, EmptyMutation, EmptySubscription)
    .enable_federation()
    .finish();
  // ... Start your server of choice
}

This will define the @link directive on your schema to enable Federation v2.

Entities and @key

Entities are a core feature of federation, they allow multiple subgraphs to contribute fields to the same type. An entity is a GraphQL type with at least one @key directive. To create a @key for a type, create a reference resolver using the #[graphql(entity)] attribute. This resolver should be defined on the Query struct, but will not appear as a field in the schema.

Even though a reference resolver looks up an individual entity, it is crucial that you use a dataloader in the implementation. The federation router will look up entities in batches, which can quickly lead the N+1 performance issues.

Example

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
struct User { id: ID }
struct Query;

#[Object]
impl Query {
    #[graphql(entity)]
    async fn find_user_by_id(&self, id: ID) -> User {
        User { id }
    }

    #[graphql(entity)]
    async fn find_user_by_id_with_username(&self, #[graphql(key)] id: ID, username: String) -> User {
        User { id }
    }

    #[graphql(entity)]
    async fn find_user_by_id_and_username(&self, id: ID, username: String) -> User {
        User { id }
    }
}
}

Notice the difference between these three lookup functions, which are all looking for the User object.

• find_user_by_id: Use id to find a User object, the key for User is id.

• find_user_by_id_with_username: Use id to find an User object, the key for User is id, and the username field value of the User object is requested (e.g., via @external and @requires).

• find_user_by_id_and_username: Use id and username to find an User object, the keys for User are id and username.

The resulting schema will look like this:

type Query {
  # These fields will not be exposed to users, they are only used by the router to resolve entities
  _entities(representations: [_Any!]!): [_Entity]!
  _service: _Service!
}

type User @key(fields: "id") @key(fields: "id username") {
  id: ID!
}

Defining a compound primary key

A single primary key can consist of multiple fields, and even nested fields, you can use InputObject to implements a nested primary key.

In the following example, the primary key of the User object is key { a b }.

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
struct User { key: Key }
#[derive(SimpleObject)]
struct Key { a: i32, b: i32 }
#[derive(InputObject)]
struct NestedKey {
  a: i32,
  b: i32,
}

struct Query;

#[Object]
impl Query {
  #[graphql(entity)]
  async fn find_user_by_key(&self, key: NestedKey) -> User {
    let NestedKey { a, b } = key;
    User { key: Key{a, b} }
  }
}
}

The resulting schema will look like this:

type Query {
  # These fields will not be exposed to users, they are only used by the router to resolve entities
  _entities(representations: [_Any!]!): [_Entity]!
  _service: _Service!
}

type User @key(fields: "key { a b }") {
  key: Key!
}

type Key {
  a: Int!
  b: Int!
}

Creating unresolvable entities

There are certain times when you need to reference an entity, but not add any fields to it. This is particularly useful when you want to link data from separate subgraphs together, but neither subgraph has all the data.

If you wanted to implement the products and reviews subgraphs example from the Apollo Docs, you would create the following types for the reviews subgraph:

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
struct Review {
    product: Product,
    score: u64,
}

#[derive(SimpleObject)]
#[graphql(unresolvable)]
struct Product {
    id: u64,
}
}

This will add the @key(fields: "id", resolvable: false) directive to the Product type in the reviews subgraph.

For more complex entity keys, such as ones with nested fields in compound keys, you can override the fields in the directive as so:

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
#[graphql(unresolvable = "id organization { id }")]
struct User {
    id: u64,
    organization: Organization,
}

#[derive(SimpleObject)]
struct Organization {
    id: u64,
}
}

However, it is important to note that no validation will be done to check that these fields exist.

@shareable

Apply the @shareable directive to a type or field to indicate that multiple subgraphs can resolve it.

@shareable fields

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
#[graphql(complex)]
struct Position {
  #[graphql(shareable)]
  x: u64,
}

#[ComplexObject]
impl Position {
  #[graphql(shareable)]
  async fn y(&self) -> u64 {
    0
  }
}
}

The resulting schema will look like this:

type Position {
  x: Int! @shareable
  y: Int! @shareable
}

@shareable type

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
#[graphql(shareable)]
struct Position {
  x: u64,
  y: u64,
}
}

The resulting schema will look like this:

type Position @shareable {
  x: Int!
  y: Int!
}

@inaccessible

The @inaccessible directive is used to omit something from the supergraph schema (e.g., if it's not yet added to all subgraphs which share a @shareable type).

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
#[graphql(shareable)]
struct Position {
  x: u32,
  y: u32,
  #[graphql(inaccessible)]
  z: u32,
} 
}

Results in:

type Position @shareable {
  x: Int!
  y: Int!
  z: Int! @inaccessible
}

@override

The @override directive is used to take ownership of a field from another subgraph. This is useful for migrating a field from one subgraph to another.

For example, if you add a new "Inventory" subgraph which should take over responsibility for the inStock field currently provided by the "Products" subgraph, you might have something like this:

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
struct Product {
  id: ID,
  #[graphql(override_from = "Products")]
  in_stock: bool,
}
}

Which results in:

type Product @key(fields: "id") {
  id: ID!
  inStock: Boolean! @override(from: "Products")
}

@external

The @external directive is used to indicate that a field is usually provided by another subgraph, but is sometimes required by this subgraph (when combined with @requires) or provided by this subgraph (when combined with @provides).

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
struct Product {
  id: ID,
  #[graphql(external)]
  name: String,
  in_stock: bool,
}
}

Results in:

type Product {
  id: ID!
  name: String! @external
  inStock: Boolean!
}

@provides

The @provides directive is used to indicate that a field is provided by this subgraph, but only sometimes.

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
struct Product {
    id: ID,
    #[graphql(external)]
    human_name: String,
    in_stock: bool,
}

struct Query;

#[Object]
impl Query {
    /// This operation will provide the `humanName` field on `Product
    #[graphql(provides = "humanName")]
    async fn out_of_stock_products(&self) -> Vec<Product> {
      vec![Product {
        id: "1".into(),
        human_name: "My Product".to_string(),
        in_stock: false,
      }]
    }
    async fn discontinued_products(&self) -> Vec<Product> {
        vec![Product {
            id: "2".into(),
            human_name: String::new(),  // This is ignored by the router
            in_stock: false,
        }]
    }
    #[graphql(entity)]
    async fn find_product_by_id(&self, id: ID) -> Product {
        Product {
            id,
            human_name: String::new(),  // This is ignored by the router
            in_stock: true,
        }
    }
}
}

Note that the #[graphql(provides)] attribute takes the field name as it appears in the schema, not the Rust field name.

The resulting schema will look like this:

type Product @key(fields: "id") {
    id: ID!
    humanName: String! @external
    inStock: Boolean!
}

type Query {
    outOfStockProducts: [Product!]! @provides(fields: "humanName")
    discontinuedProducts: [Product!]!
}

@requires

The @requires directive is used to indicate that an @external field is required for this subgraph to resolve some other field(s). If our shippingEstimate field requires the size and weightInPounts fields, then we might want a subgraph entity which looks like this:

type Product @key(fields: "id") {
  id: ID!
  size: Int! @external
  weightInPounds: Int! @external
  shippingEstimate: String! @requires(fields: "size weightInPounds")
}

In order to implement this in Rust, we can use the #[graphql(requires)] attribute:

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
#[graphql(complex)]
struct Product {
  id: ID,
  #[graphql(external)]
  size: u32,
  #[graphql(external)]
  weight_in_pounds: u32,
}

#[ComplexObject]
impl Product {
  #[graphql(requires = "size weightInPounds")]
  async fn shipping_estimate(&self) -> String {
    let price = self.size * self.weight_in_pounds;
    format!("${}", price)
  }
}
}

Note that we use the GraphQL field name weightInPounds, not the Rust field name weight_in_pounds in requires. To populate those external fields, we add them as arguments in the entity resolver:

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
struct Product {
    id: ID,
    #[graphql(external)]
    size: u32,
    #[graphql(external)]
    weight_in_pounds: u32,
}
struct Query;
#[Object]
impl Query {
  #[graphql(entity)]
  async fn find_product_by_id(
    &self, 
    #[graphql(key)] id: ID, 
    size: Option<u32>, 
    weight_in_pounds: Option<u32>
  ) -> Product {
    Product {
      id,
      size: size.unwrap_or_default(),
      weight_in_pounds: weight_in_pounds.unwrap_or_default(),
    }
  }
}
}

The inputs are Option<> even though the fields are required. This is because the external fields are only passed to the subgraph when the field(s) that require them are being selected. If the shippingEstimate field is not selected, then the size and weightInPounds fields will not be passed to the subgraph. Always use optional types for external fields.

We have to put something in place for size and weight_in_pounds as they are still required fields on the type, so we use unwrap_or_default() to provide a default value. This looks a little funny, as we're populating the fields with nonsense values, but we have confidence that they will not be needed if they were not provided. Make sure to use @requires if you are consuming @external fields, or your code will be wrong.

Nested @requires

A case where the @requires directive can be confusing is when there are nested entities. For example, if we had an Order type which contained a Product, then we would need an entity resolver like this:

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
pub struct Order { id: ID }
struct Query;
#[Object]
impl Query {
  #[graphql(entity)]
  async fn find_order_by_id(&self, id: ID) -> Option<Order> {
      Some(Order { id })
  }
}
}

There are no inputs on this entity resolver, so how do we populate the size and weight_in_pounds fields on Product if a user has a query like order { product { shippingEstimate } }? The supergraph implementation will solve this for us by calling the find_product_by_id separately for any fields which have a @requires directive, so the subgraph code does not need to worry about how entities relate.

@tag

The @tag directive is used to add metadata to a schema location for features like contracts. To add a tag like this:

type User @tag(name: "team-accounts") {
  id: String!
  name: String!
}

You can write code like this:

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[derive(SimpleObject)]
#[graphql(tag = "team-accounts")]
struct User {
  id: ID,
  name: String,
}
}

@composeDirective

The @composeDirective directive is used to add a custom type system directive to the supergraph schema. Without @composeDirective, and custom type system directives are omitted from the composed supergraph schema. To include a custom type system directive as a composed directive, just add the composable attribute to the #[TypeDirective] macro:

#![allow(unused)]
fn main() {
extern crate async_graphql;
use async_graphql::*;
#[TypeDirective(
    location = "Object",
    composable = "https://custom.spec.dev/extension/v1.0",
)]
fn custom() {}
}

In addition to the normal type system directive behavior, this will add the following bits to the output schema:

extend schema @link(
	url: "https://custom.spec.dev/extension/v1.0"
	import: ["@custom"]
)
	@composeDirective(name: "@custom")