Guided examples of Schema Stitching doing awesome things. Focuses on the new (GraphQL Tools v6+) stitching using type merging, not legacy Apollo Stitching (opens in a new tab).

This handbook initially created by Greg MacWilliam (opens in a new tab)

Table of Contents

Foundation

• Combining local and remote schemas

  • Adding a locally-executable schema.
  • Adding a remote schema, fetched via introspection.
  • Adding a remote schema, fetched from a custom SDL service.
  • Avoiding schema conflicts using transforms.
  • Authorization headers.
  • Basic error handling.

• Mutations & subscriptions

  • Adding a remote mutation service.
  • Adding a remote subscription service.
  • Adding a subscriber proxy.

• Single-record type merging

  • Type merging using single-record queries.
  • Query/execution batching.

• Array-batched type merging

  • Type merging using array queries.
  • Handling array errors.
  • Nullability & error remapping.

• Merged types with multiple keys

  • Configuring multiple key entry points for a merged type.

• Nullable merges

  • Selecting nullability for merged fields.
  • Returning nullable and not-nullable results.

• Custom merge resolvers

  • Using valuesFromResults to normalize resulting query data.
  • Adapting type merging to query through namespaced scopes.
  • Adapting type merging to query through non-root fields.
  • Using batchDelegateToSchema and delegateToSchema.

• Cross-service interfaces

  • Distributing a GraphQL interface across services.

• Computed fields

  • Configuring computed fields.
  • Sending complex inputs to subservices.
  • Normalizing subservice deprecations in the gateway.

• Stitching directives SDL

  • @key directive for type-level selection sets.
  • @merge directive for type merging services.
  • @computed directive for computed fields.
  • @canonical directive for preferred element definitions.

Architecture

• Hot schema reloading

  • Hot reload of the combined gateway schema (no server restart).
  • Polling for remote subschema changes.
  • Mutations for adding/removing remote subservices.
  • Handling subservice request timeouts.

• Versioning schema releases

  • Using GitHub API to manage a simple schema registry.
  • Hot reloading from a remote Git registry.
  • Running development and production environments.

• Continuous Integration (CI) testing

  • Adding test coverage to a stitched schema.
  • Mocking subservices as local test fixtures.

• Public and private APIs

  • Filtering unwanted fields from the final stitched schema.
  • Serving public (filtered) and private (unfiltered) API versions.

• Persistent connection via WebSockets

  • Creating a GraphQL over WebSocket Protocol (opens in a new tab) executor for the persistent connection to the services.

Other Integrations

• Federation services

  • Integrating Apollo Federation services into a stitched schema.
  • Fetching and parsing Federation SDLs.

• Subservice languages

  • JavaScript schemas created with:

    • graphql-js
    • nexus
    • type-graphql

  • Ruby schemas created with:

    • Class-based definitions
    • Parsed definitions string

• GraphQL Upload

  • Adding GraphQL Upload to the gateway server

Appendices

• What is Array Batching?
• What is Query Batching?