GraphQL introspection queries: How to query and explore GraphQL APIs

GraphQL introspection is a feature of GraphQL APIs that lets you query information about the structure of the API, including its schemas, types, and other features. This guide defines what GraphQL introspection is, explains how you can use it to improve your development workflows, and provides example GraphQL introspection queries that you can adapt for your own use.

What is GraphQL introspection?

GraphQL introspection queries a GraphQL API schema to return information about the structure and features of the API.

This makes GraphQL APIs self-documenting (meaning that you can find out everything you need to know to use an API from the API itself, without needing external documentation and tools like Swagger), and allows for integration with developer tools to provide type-checking and autocompletion.

What makes a GraphQL schema?

The components of a GraphQL API are detailed in the results of a GraphQL introspection query to the schema:

Below is a basic GraphQL introspection query example that requests the name of the root query type in the schema:

The response will include the result of the query, in this case showing that the name of the root query type is "Query" (which is the default for GraphQL APIs):

How does GraphQL introspection benefit developers?

GraphQL introspection is one of the developer-friendly features that elevates GraphQL over REST APIs for more complex use cases. The functionality provided by GraphQL introspection can be leveraged to provide the following benefits to developers:

• Self-documentation and self-service: Automatically generate API documentation by querying the schema. Developers can query the API themselves if separate documentation is not provided or if they do not have access to the underlying database to view its structure/fields.

• Query optimization: Understand the exact structure of the API so that you can optimize your queries and avoid over- or under-fetching data.

• Compatibility with evolving schemas: Some schemas change a lot, and introspection allows developers to check that things will still work the way they expect them to.

• Type checking and auto-completion: GraphQL-enabled IDEs like GraphiQL, Apollo Studio, or Visual Studio Code with the GraphQL extension can provide autocomplete suggestions for your fields, arguments, and types. This saves time and reduces errors since you don't need to stop and check documentation.

Introspection queries make information about the structure and contents of an API information readily available to developers, and the information is returned in a format that can be used programmatically by clients.

This allows you to write code that automatically determines what an API provides, saving time and making sure front ends are consistent with what their back-end APIs make available, even if it changes.

For example, rather than manually creating (and maintaining) individual forms for searching, creating, and updating a variety of different objects in an API, you can perform an introspection query, find out what is available, and dynamically generate forms based on that.

Example: How to explore a GraphQL schema with introspection queries

A GraphQL introspection query looks like any other GraphQL query and uses the __schema and __type fields, which exist purely for introspection purposes and provide information about the API itself.

The __schema field returns high-level information about the entire schema. The GraphQL introspection query example below fetches high-level info about all of the data types available from an API:

The __type field returns the details of a single specific type (a field, argument, etc.). The example below retrieves information about a BlogPost type:

The result of this introspection query would look something like this when run against a live GraphQL API:

Example: How to fetch an entire schema using introspection

The below GraphQL introspection query example can be used with any GraphQL API that supports introspection queries, and it will retrieve information about the entire schema:

This query inspects the entire GraphQL schema and retrieves detailed information about:

• All of the types in the schema.

• The fields and arguments of each type.

• The root operation types: Query, Mutation, and Subscription.

• The directives supported by the schema, including their names, locations, and arguments.

GraphQL introspection best practices

GraphQL introspection is a great aid to developers and can be further enhanced by following GraphQL best practices:

• Keep queries small by filtering your queries to only get the data you need. Querying the whole schema is resource intensive, and some servers enforce query depth or execution time limits.

• Batch queries and cache the results locally to further reduce strain on the server.

• Use tools like GraphiQL and Apollo Studio to help you write introspection queries, and leverage type checking and auto-completion.

• If your queries do not return the expected results, check for deprecated fields or server misconfiguration.

• If your GraphQL introspection query fails with a 401 Unauthorized or 403 Forbidden error, you need to authenticate. Verify that you have included the correct HTTP authorization headers and that you have the correct permissions on the server to perform introspection queries.

A common piece of advice for GraphQL APIs is to disable introspection queries in production to prevent malicious actors from using them to find information about your API. This isn't always sound advice, however: Attackers have other ways to find out your API structure (such as GraphQLer and Zap), so at best, you're just slowing them down while making your developers less efficient and limiting what your front ends can do.

The security of your GraphQL APIs should be enforced with robust authorization and access control, which can be used to specifically grant or deny access to introspection queries, rather than enforcing security through obscurity.

GraphQL lets developers leverage the full potential of APIs

Online platforms are increasingly deploying GraphQL APIs due to its powerful developer features and tools, including GraphQL introspection.

Contentful provides a fully composable back end for your applications, allowing you to define the text, images, videos, and other assets you need to publish to your apps and websites. We provide a central web-based interface for creating and managing your full library of content backed by a GraphQL API that you can connect to your apps and websites, and we fully support GraphQL introspection too.

Start building

Sign up for a free Contentful account

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.