Growing up GraphQL

2022-05-25 / Élénie Godzaridis

…with

377

how many GraphQL schemas Wealthsimple has today

September 2016

when Wealthsimple got its first GraphQL API

Today’s Agenda

• What’s GraphQL?
• What about all the REST?
• Good tools, bad tools, best tools
• Front-end, backend, odds and ends
• Schema registries and naming things
• What’s wrong with GraphQL and does it matter?
• Next up

What’s GraphQL

• GraphQL is primarily �a language that API queries can be written in.
• It’s sent over HTTP GET or POST to a GraphQL API endpoint (usually /api/graphql)

GraphQL query example

Reusable

Concise

What about all the REST?

We used to have REST APIs.

​

Most likely, so did you.

Then…

The payloads got pretty large and it felt frustratingly inefficient (especially for mobile).

We didn’t like dealing with adding large numbers of optional parameters.

We wanted a schema registry.

Once upon a time…

Major Departures from REST

• Deciding to go schema-first with GraphQL
• Monitoring/tracing differences
• Pagination
• Documentation

(the way we did)

API Documentation

• GraphQL lets people write queries using only the fields they need
• documentation for schemas with many fields can be harder to navigate.
• Using playgrounds instead of Swagger-like autogenerated docs

API Documentation

• We have pages for each API in our internal instance of Backstage
• Each page also�has a GraphiQL�plugin to explore�that API.
• (REST APIs have �equivalent auto-�generated OpenAPI�docs sites.)

Good Tools, Bad Tools, Best Tools

The Guild (https://www.the-guild.dev/about-us)

“We do open source slow but well.”

We use

• GraphQL Tools
• Apollo Client
• graphql-codegen
• graphql-eslint
• Datadog

• Tools are useful for
• schema linting (using the right names!)
• stitching
• having CI check everything
• tracing calls (but this is not perfect)

Tracing and monitoring

• Life without the “non-200 status rate” rule
• Datadog APM works well, but optimization is still a lot of work
• More control to clients = more interest in monitoring what they do

We looked at

• Apollo Studio/Federation

https://www.apollographql.com/docs/federation/

Front-end, backend, odds and ends

• Faster feedback loop on the frontend
• Most things can be done with a single request
• Types can be autogenerated from the schema
• With all the investment in GraphQL based tooling, it made sense to also use it in service-to-service calls.

Mock API servers

• We have an @example directive that’s used to generate template servers that people can run locally to get fake data.

​

​

Schema registries and naming things

ws-schemas

• Our schema registry ws-schemas is where all definitions for the types in our APIs are housed.
• Why keep all schemas in the�same spot? We want people�to be able to share common�definitions and to have a�single source of truth.

Schema stitching

• Growing org => more schemas (as seen in first slide) => a need to break down schemas into parts that can be owned alongside a service.
• We use schema stitching for this:
• Combining multiple schemas into a gateway schema

Schema #1

Schema #2

Schema #3

Gateway schema

End User App

What’s wrong with GraphQL and does it matter?

Gotchas people find

• Monitoring is (slightly) harder

​

• Documentation doesn’t tell you how to use the API

​

• Requires more tooling and discipline around use (errors, types, etc)

​

​

Not really true. Requires different monitors.

You can give examples in documentation. GitHub’s does. In general, GraphQL APIs aren’t as opinionated on intended use.

We learned that one the hard way where when possible you want common types, common errors, etc.

Next up

How using GraphQL is changing our architecture

• Subscriptions and async APIs
• Per-field usage tracking
• GraphQL Gateways
• Less contract testing, more integration tests