Catch the highlights of GraphQLConf 2023! Click for recordings. Or check out our recap blog post.
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