DEV Community

Cover image for GraphQL Tools v7 delivers the next generation GraphQL API Gateway
TheGuildBot for The Guild

Posted on • Updated on • Originally published at the-guild.dev

GraphQL Tools v7 delivers the next generation GraphQL API Gateway

This article was published on Tuesday, November 3, 2020 by Arda Tanrikulu @ The Guild Blog

Ever since The Guild took over GraphQL Tools, we've been getting feedback
from companies using a variety of industry tools and have been working to transform Schema Stitching
into the best GraphQL gateway solution for their needs. Today we are happy to announce GraphQL Tools
v7, which brings Schema Stitching to a whole new level thanks to automation and performance
enhancements.

Try out Schema Stitching by following the instructions on the
new docs, or follow the
migration guides

Why Schema Stitching

We believe Schema Stitching is the simplest and most extensible way to federate your GraphQL
services, building upon some new and existing features:

  • Type merging allows partial definitions of a type to exist in any subschema, all of which are merged into one unified type in the gateway schema. When querying for a merged type, the gateway smartly delegates portions of a request to each relevant subschema in dependency order, and then combines all results for the final return.

In addition to just merging basic object types, schema stitching allows interfaces, unions, and
element descriptions to be merged across services. This merging paradigm encourages
independently valid subschemas,
versus patterns such as Apollo Federation where subservices are left with holes to be backfilled by
the top-level gateway service.

  • Computed fields allow
    type merging to also implement the
    Federation service pattern
    for those seeking the best of both worlds. While basic merge patterns are simpler and more
    durable, you may still find cases where it's useful to send representations of a type into a
    service (federation pattern), rather than exposing a service's types to other services (merge
    pattern). Users coming from Apollo Federation may also appreciate how stitching's decentralized
    graph allows keys to be selected from anywhere versus just from a dedicated “origin” service.

  • Batch performance is now a core
    offering of Schema Stitching thanks to built-in tools for field-level and query-level batching.
    With the flip of a switch, query batching will consolidate all requests made to a service into a
    single GraphQL query, thus flattening out both networking and querying costs to a single operation
    per service per generation of data.

  • Extensibility remains a core concern of Schema Stitching, so classic schema extensions and
    transforms remain fully interoperable with the new automated merging features. These features
    support wrapping, hoisting, and bridging fields in any custom configuration that you may require.
    This interoperability makes migrating to the newer merge features quite simple – just enable
    merging, and then replace your classic extensions with merges one at a time. As always, the end
    product of schema stitching is a gateway schema fully compatible with all the tools of the
    JavaScript GraphQL ecosystem.

  • Subscriptions Support

  • Run anywhere One interesting option when you use Schema Stitching, is the ability to run it
    completely client-side. It might sound weird at first, but many times you can actually use it to
    get started quickly, without the need of introducing a new gateway or server into your stack.
    Checkout
    this talk
    discussing why and how.

Above although – Schema Stitching lets you use “Just GraphQL”. No complex DSLs or Node-specific
subservice packages are required. This makes Schema Stitching easy to use atop GraphQL services
implemented in any language, and easy to explain while onboarding team members. Also, (mostly thanks
to our wonderful community) we have very detailed docs on all stitching features. Make sure to
check them out!

But don't take our word for it, Check out
this comprehensive blog post
from Vox Media's product team about their
evaluation of Schema Stitching vs. Apollo Federation, their conclusions and their usage of Schema
Stitching in production and at scale.

Relationship with GraphQL Mesh

The Guild is also maintaining the popular GraphQL Mesh library, and often
we get asked about the relationship of GraphQL Mesh with Schema Stitching and Apollo Federation.

The main goal of GraphQL Mesh is to connect non-GraphQL services (Swagger/OpenAPI, gRPC,
json-schema, SOAP and others) into your gateway, whether your gateway uses Schema Stitching or
Apollo Federation as your merging strategies.

In GraphQL Mesh you can pick and choose between Schema Stitching and Apollo Federation. Recently,
with all the new improvements to Schema Stitching and the need to support GraphQL Subscriptions in
GraphQL Mesh, we have made Schema Stitching the default choice, with merging via Apollo Federation
still easily configurable.

Currently, you are able to use both Schema Stitching and Apollo Federation merging strategies with
the declarative API of GraphQL Mesh without writing single line of code or adding anything in
SDL.The idea is to apply necessary transforms and metadata for the gateway by keeping the original
source of the services.

Here is an example for Schema Stitching;

sources: # Here we have two independent sources
  - name: Covid
    handler:
      graphql:
        endpoint: https://covid-19.dava.engineer/api/graphql
  - name: WorldPop
    handler:
      jsonSchema:
        baseUrl: https://datasource.kapsarc.org/api/records/1.0/search
        operations:
          - type: Query
            field: population
            path: /?dataset=world-population&q={args.country}&rows=1&sort=year&facet=year&facet=country_name
            method: GET
            responseSchema: ./src/json-schemas/worldPop.json

# In Schema Stitching, we define how to stitch those schemas on root level instead of source level
# as in federation

# Also in schema stitching, we extend the unified schema instead of transforming the source schemas.
additionalTypeDefs: |
  extend type Case {
    population: ApiPopulation
  }
  extend type Query {
    stat(country: String!): Stat
  }
  type Stat {
    confirmedRatio: Float
    deathRatio: Float
    recoveredRatio: Float
    case: Case
    population: ApiPopulation
  }
# In here, we define our stitching resolvers without using any single line of code
additionalResolvers:
  - type: Case
    field: population
    requiredSelectionSet: |
      {
        countryRegion
      }
    targetSource: WorldPop
    targetMethod: population
    args:
      country: '{root.countryRegion}'
Enter fullscreen mode Exit fullscreen mode

Here is an example for Apollo Federation;

merger: federation # Apollo Federation is used to merge the following sources as federated services
sources:
  - name: accounts
    handler:
      graphql:
        endpoint: http://localhost:4001/graphql # This is a standalone GraphQL API that doesn't have any federation metadata
    transforms: # Using federation transform, we can convert it to a federated service
      - federation:
          types:
            - name: Query
              config:
                extend: true
            - name: User
              config:
                keyFields:
                  - id
                resolveReference:
                  targetSource: accounts
                  targetMethod: user
                  args:
                    id: root.id
Enter fullscreen mode Exit fullscreen mode

What's Next?

We are working to continuously improve Schema Stitching and the rest of the GraphQL Tools, and we
want together as much feedback as possible in terms of community experiences, feature requests, bug
reports, and even new directions.

That said, our next goal is to improve the overall experience working with multiple services and
updating the gateway accordingly.

First, we are aiming for a new schema registry package. We plan on using
GraphQL Inspector to check for breaking changes on individual
services and the schema gateway as a whole. And thanks to GraphQL Mesh, that process will work for
any type of service schema, not just GraphQL!

Second, we are hoping to simplify type merging configuration via a declarative API -- similar to the
work with computed fields -- without losing the power you get today with Schema Stitching's type
merging.

Finally, naming - Naming is hard. While Schema Stitching is a great name, the above improvements
have been transformative, and it may be time for a new term to describe this powerful and
configurable method of creating a gateway schema.

We are thinking about GraphQL Portal or just GraphQL Gateway to describe this new functionality. As
always, we are hoping for your feedback and ideas!

Top comments (0)