Five Useful Introspection Queries

We all love type systems, or at least, most of us can agree that type systems are generally good. They can help us eliminate bugs. They provide a formal structure which makes it possible incorporate tooling and automation. They give us a way to communicate about the structure of our code. So if type systems are good, then you should be in love with GraphQL. GraphQL is a type system for your API.

In GraphQL, all types are defined in a schema. Every GraphQL API has one. You can surf the schema by using the "Docs" tab in GraphiQL, or the "Schema" tag in GraphQL Playground. Both GraphiQL and GraphQL playground construct the schema document explorer by querying the endpoint for details about the schema itself. These queries are called introspection queries, and you can send them to GraphQL APIs yourself.

This article explores some common introspection queries that you can use for everything from helping to understand a GraphQL API to building tooling and automation for the GraphQL ecosystem. Let's have some fun! Load up GraphiQL or the GraphQL Playground and plug in your favorite GraphQL endpoint. You are about to ask that endpoint questions about itself.

If you don't have a favorite GraphQL API you can use the Snowtooth API. It is real GraphQL API for a fake ski resort. You can also use the Star Wars API, or SWAPI to practice sending introspection queries. Or pick from an endpoint from this list of public GraphQL endpoints.

Querying All Available Types in a Schema

The first introspection query that I sent to a GraphQL API was a query that asked for all of the available types in that API's schema:

query allSchemaTypes {
    __schema {
        types {
            name 
            kind
            description
        }
    }
}

Using the __schema field, we can ask a GraphQL API to provide a list of all of the types defined in the schema. This particular query will return the name and description for each type. We also ask for the kind of each type. The kind refers to the GraphQL constructor that was used to define the type: SCALAR, OBJECT, INTERFACE, UNION, ENUM, INPUT_OBJECT, LIST, NON_NULL. This query provides a general overview of what types are available on a particular GraphQL endpoint.

If the description field returns null, that means that type descriptions were not supplied with the schema. In order to take full advantage of using a type system, it is always a good idea to formally describe each type when drafting a schema.

All Available Queries

One of the first things that we need to know about an API is what are the queries that can we send to it? The following introspection query will list all of the root queries that can be sent to an api:

query availableQueries {
  __schema {
    queryType {
      fields {
        name
        description
      }
    }
  }
}

The __schema field allows us to ask for the queryType, which returns the query type OBJECT that contains of the root queries that we can send to that endpoint. Listing the fields of this OBJECT will supply a list of those available root queries. Here we are asking for the name and description of each field. You can also find all of the root mutations by querying the mutationType or all of the root subscriptions by querying the subscriptionType.

Details about an Individual Type

Once you have received a list of types you can send a introspection query that asks for the details about any individual type:

# Replace <TYPE> with the name of an actual type
query liftType {
  __type(name: "<TYPE>") {
    fields {
      name
      description
    }
  }
}

We must supply a name for the type that we wish to query in the above example. If you are using Snowtooth you can query the "Lift" or "Trail" type. If you are using SWAPI, you can ask for the "Film" or "Species" type.

This query returns details about a specific type. In this case we are asking for the name and description of every field defined in a specific type.

List of Enumerator Values

Enumerators in GraphQL are great. They allow us to restrict possible values for a field to a specific list. When you want to know what those values are, you can send the following introspection query:

# Replace <ENUM TYPE> with the name of an actual enumeration type
query EnumerationValues {
  __type(name: "<ENUM TYPE>") {
    kind
    name
    description
    enumValues {
      name
      description
    }
  }
}

The above query asks for the kind, name, and description of the enumeration type as well as a list of enumValues. This will provide the name and description of each option that is defined in the enumeration type.

We can only query enumeration values on ENUM types. This means that the kind of type has to be an ENUM. If you are using snowtooth you can query the "LiftStatus". If you are using an API that does not define any enums in the schema you can always use "__TypeKind". This is an ENUM type that is used for introspection. It will return a list of all of the kinds of types that are available.

All Types Associated with an Interface or Union

If your GraphQL API defines any unions or interfaces you can find out what types are associated with those unions or implemented by those interfaces:

# Replace <INTERFACE OR UNION TYPE> with the name of an actual interface or union type
query UnionInterfaceTypes {
  __type(name: "<INTERFACE OR UNION TYPE>") {
    kind
    name
    description
    possibleTypes {
      name
      kind
      description
    }
  }
}

The above query will tell you what types are associated with a union or an interface. In order to make this query work, you must use it on a GraphQL API that defines union or interface types. Unfortunately, the Snowtooth API does not define these types. However the SWAPI does have an interface called "Node", which will allow you to test this query there.

This useful query will point you to all of the objects that implement an interface type or are associated with a union type. If you queried the SWAPI for the "Node" interface, you will see the kind, name, and description of the "Node" interface as well as a list of objects that are implemented by that interface under the possibleTypes field. In SWAPI, this includes all of the main object types that contain an id.

---

Introspection queries are useful when we want to better understand a schema. We can use these queries in our code to build applications around GraphQL APIs themselves. A great example of this is GraphiQL or GraphQL Playground. Both of these tools provide an explorer that uses introspection queries to allow you to explore the schema. There are endless possibilities of what can be done when you add a type system to your API.