What is Introspection in GraphQL

GraphQL stands out with its strong type system. Because of the strong typed system, GraphQL is able to provide an introspection system to query the schema. The introspection system in GraphQL provides a way for clients to discover the resources that are available in a GraphQL schema. The introspection system is a feather in the hat for GraphQL. It has plenty of uses and we will see some of them below.

Why is Introspection Useful?

Provides clients a deep view of the schema

Through introspection queries, the client can get a complete view of the resources in the GraphQL schema. This can save the client tons of time going back and forth with documentation. Instead they can introspect the schema and understand the resources available to them in depth.

Build Awesome Tools

The introspection system allows the community to build awesome tools for GraphQL. Some of the tools that we use today that owe their existence to the introspection system are GraphiQL, GraphQL Playground, to name a few. These tools help clients to explore the GraphQL schema, in an easy and user-interactive way.

Self Documentation

These GraphQL tools like GraphQL Playground use the introspection system, to provide features like self documentation of the API, auto completion and code generation.

Introspection Queries

Let’s dive into some introspection queries and learn how to write them.

To demonstrate and learn GraphQL introspection queries, I am going to use the GitHub API that is available to the public. You can follow along by opening https://developer.github.com/v4/explorer/. Make sure you are signed in to your GitHub account to run the introspection queries.

On the GitHub GraphQL explorer, we can start typing our queries on the left side and hit play to see the JSON response on the right side. We can also browse through the documentation of the API on the right side.

Query schema’s type

All the fields in the introspection system are prefixed with two underscores. Let’s query the __schema field and learn about the types supported in the schema.

query getSchmemaTypes {
  __schema {
    types {
      name
    }
  }
}

The JSON response to this query is quite lengthy from the GitHub schema, below is the snapshot of the response.

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "AcceptEnterpriseAdministratorInvitationInput"
        },
        {
          "name": "AcceptEnterpriseAdministratorInvitationPayload"
        },
        {
          "name": "AcceptTopicSuggestionInput"
        },
        {
          "name": "AcceptTopicSuggestionPayload"
        }
        ......
       ]
    }
  }
}

Query supported queries and mutations

Using introspection we can also retrieve the supported queries and mutations from a schema. You can also use the isDeprecated field to learn if specific queries/mutations are deprecated. This will be useful information for the client before consuming the API. Within the ___schema _field, query for queryType and mutationType.

query getSupportedQueries {
  __schema {
    queryType {
      fields{
        name
      }
    }
  }
}

The JSON response below shows the queries supported by the API.

{
  "data": {
    "__schema": {
      "queryType": {
        "fields": [
          {
            "name": "codeOfConduct"
          },
          {
            "name": "codesOfConduct"
          },
          {
            "name": "enterprise"
          },
          {
            "name": "enterpriseAdministratorInvitation"
          },
          {
            "name": "enterpriseAdministratorInvitationByToken"
          },
          {
            "name": "license"
          },
          {
            "name": "licenses"
          },
          {
            "name": "marketplaceCategories"
          },
          {
            "name": "marketplaceCategory"
          },
          {
            "name": "marketplaceListing"
          },
          {
            "name": "marketplaceListings"
          },
          {
            "name": "meta"
          },
          {
            "name": "node"
          },
          {
            "name": "nodes"
          },
          {
            "name": "organization"
          },
          {
            "name": "rateLimit"
          },
          {
            "name": "relay"
          },
          {
            "name": "repository"
          },
          {
            "name": "repositoryOwner"
          },
          .....
      }
    }
  }
}

#graphql #database #programming #developer