GraphQL API diagnostic tools

This article shows you how to use a couple of GraphQL API diagnostic tools to help solve some common issues.

Debugging a schema

If you're unable to see your schema in a schema introspection tool like Apollo API Explorer in Prepr or when making requests through Postman, it's useful to run an endpoint diagnosis to verify the schema is valid. In this case, you can debug the schema as follows:

1. Use an API diagnostic tool to debug the broken schema by executing the following command in the terminal:

   npx diagnose-endpoint@1.1.0 --endpoint="<YOUR-API-ENDPOINT>"

2. Replace the placeholder value <YOUR-API-ENDPOINT> with the API URL of the access token from Prepr.

You know that the schema is well-formed when you get the message: Could not find any problems with the endpoint.

Otherwise, the tool displays an error message like one of the following:

• ⚠️ Invalid schema from introspection: Union type AllModels must define one or more member types. -> This means your schema is completely empty.
• Cannot query field "fieldName" on type "TypeName".
• Expected type "TypeName", found "InvalidType"
• Type "TypeName" was defined more than once.

The detailed error message helps you pinpoint the entity or field that resulted in the corrupted schema.

Checking the difference between two schemas

The GraphQL Schema Diff tool (opens in a new tab) identifies differences between two GraphQL schemas, making it useful for the following cases:

• Before syncing two schemas across environments, it's a good idea to check for differences that could cause breaking changes before you start.
• Comparing two different API versions for the same environment, for example, when upgrading your API.

Run the graphql-schema-diff tool to view differences between two schemas or two API versions as follows:

1. Install the GraphQL Schema Diff tool by executing the following command in the terminal:

   npm install -g graphql-schema-diff

2. Once installed, you can run the tool with the following command:

   graphql-schema-diff <SCHEMA-1-API-ENDPOINT> <SCHEMA-2-API-ENDPOINT> -s

3. Replace the placeholder values <SCHEMA-1-API-ENDPOINT> and <SCHEMA-2-API-ENDPOINT> with the API URL of the access tokens for each schema you want to compare.

You'll get a similar result to the image below.

We trust that these diagnostic tools help you debug similar API-related issues more easily. Don't hesitate to reach out to Prepr support (opens in a new tab) for questions or to add your own favorite diagnostic tools to this list.