While in traditional REST API’s versioning is a hot topic, GraphQL takes a strong opinion on avoiding versioning by providing the tools for the continuous evolution of a GraphQL schema. As GraphQL only returns the data that is explicitly requested, it becomes easier to introduce new functionality by adding new types and fields without introducing breaking changes. As you know what fields are used by which clients you can have a lot more knowledge in your hands to prevent breaking your clients.
For small schema’s it can be feasible to inspect your schema for changes manually but for larger schemas or federated schema’s good tooling becomes a necessity.
A tool that can help you to achieve this is GraphQL Inspector.
It offers the following (free) features:
- Compares schemas
- Detect breaking or dangerous changes
- Schema change notifications
- Use serverless functions validate changes
- Validates Operations and Fragments against a schema
- Finds similar / duplicated types
- Schema coverage based on Operations and Fragments
- Serves a GraphQL server with faked data and GraphiQL
- Docker Image
Getting started
To get started you have multiple items. You can use it as a Github application, a Github action but also as a commandline tool.
Let’s see how to use the commandline tool:
npm install --global @graphql-inspector/cli graphql
Now we can compare two schema’s:
graphql-inspector diff old.graphql new.graphql
Detected the following changes (2) between schemas:
√ Description was removed from field Post.createdAt
√ Field Post.createdAt changed type from String to String!
success No breaking changes detected
It is a must have for every GraphQL developer!