gmac / schema-stitching-handbook

Guided examples exploring GraphQL Tools v6+ Schema Stitching

Guided examples of GraphQL Stitching doing useful things. While this book focuses on GraphQL Tools (JavaScript) and its specific capabilities, many of these general schema stitching concepts apply to implementations across languages, see similar projects:

• Bramble (Golang)
• graphql-stitching-ruby (Ruby)

Table of Contents

Installation

From the root directory, run:

yarn install

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.

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?