Table of Contents

Schema Stitching Handbook

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

This handbook initially created by Greg MacWilliam

Table of Contents


  • 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.


Other Integrations

  • Federation Supergraph

    • Consume a Federation Supergraph SDL in Schema Stitching
    • No conversion needed from Federation SDL to Stitching SDL
  • Federation to Stitching SDL

    • Converting Federation SDL to Stitching SDL
    • 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