The following is the first few sections of a chapter from The Busy Coder's Guide to Android Development, plus headings for the remaining major sections, to give you an idea about the content of the chapter.


Introspection

When we query a GraphQL server, we request root fields and sub-fields of those roots, sub-sub-fields of those sub-fields, and so forth, creating a tree of results.

The fields that we have focused on to date have been data: trips, plans, and things like that. However, GraphQL also has another set of fields representing metadata about what we are querying. This set of fields allows tools like GraphiQL to know the nature of what the server understands, so the tools can guide you, generate code for you (as with Apollo-Android), and so forth. Those fields can also be useful to you as part of your normal GraphQL requests, to give you some context around the response that you get.

These metadata fields form GraphQL’s introspection system, which we will focus on in this chapter.

Adding a Type To Your Response

In a previous chapter, we examined how to query on interfaces and unions. However, savvy developers will have noticed a bit of a hole in our query and its response: we do not get any information about what we are getting back.

For example, we had this GraphQL document:

query getAllTrips {
  allTrips {
    ...planFields
    plans {
      ...planFields
    }
  }
}

fragment planFields on Plan {
  id
  title
  startTime
  priority
  duration
  creationTime
}

That, in turn, generates this JSON response:

{
  "data": {
    "allTrips": [
      {
        "id": "2c494055-78bc-430c-9ab7-19817f3fc060",
        "title": "Vacation!",
        "startTime": "2017-12-20T13:14:00-05:00",
        "priority": "MEDIUM",
        "duration": 10080,
        "creationTime": "2017-02-19T15:21:58.547Z",
        "plans": [
          {
            "id": "319185bd-fab0-49e3-86ce-251d2aaa5d23",
            "title": "Flight to Chicago",
            "startTime": "2017-12-20T13:14:00-05:00",
            "priority": "HIGH",
            "duration": 150,
            "creationTime": "2017-02-19T15:21:58.547Z"
          },
          {
            "id": "319185bd-fab0-49e3-86ce-251d2aaa5d23",
            "title": "House of Munster",
            "startTime": "2017-12-20T15:00:00-05:00",
            "priority": "MEDIUM",
            "duration": 9900,
            "creationTime": "2017-02-19T15:21:58.547Z"
          }
        ]
      },
      {
        "id": "e323fed5-6805-4bcf-8cb6-8b7a5014a9d9",
        "title": "Business Trip",
        "startTime": "2018-01-14T11:45:00-05:00",
        "priority": "HIGH",
        "duration": 4320,
        "creationTime": "2017-02-19T15:21:58.547Z",
        "plans": [
          {
            "id": "d40eb2e7-3211-422e-858c-403cbe3fa680",
            "title": "Flight to Denver",
            "startTime": "2018-01-14T11:45:00-05:00",
            "priority": "HIGH",
            "duration": 257,
            "creationTime": "2017-02-19T15:21:58.547Z"
          },
          {
            "id": "e28a591b-cdc9-4328-9e79-9e4ed60ae7d2",
            "title": "Hotel Von",
            "startTime": "2018-01-14T15:00:00-05:00",
            "priority": "MEDIUM",
            "duration": 4140,
            "creationTime": "2017-02-19T15:21:58.547Z"
          }
        ]
      }
    ]
  }
}

We get back the fields that we ask for. However, there is nothing to tell us what the underlying type is behind the objects in the plans array. As humans, we can tell that the “Flight to Denver” Plan probably is a Flight, as that would be a rather strange name for some Lodging. However, we cannot readily teach software to make that distinction, nor should we need to.

Using inline fragments can help a little:

query getAllTrips {
  allTrips {
    ...planFields
    plans {
      ...planFields
      ... on Flight {
        airlineCode
        flightNumber
        departingAirport
        arrivingAirport
      }
      ... on Lodging {
        address
      }
    }
  }
}

fragment planFields on Plan {
  id
  title
  startTime
  priority
  duration
  creationTime
}

Now, we could say that if a Plan has an airlineCode, then it is a Flight, whereas if it has an address, then it is a Lodging. However, we are making an inference of the underlying types based on the fields that we get back. Wouldn’t it be nice if the JSON just said, plainly, what each of those objects are?

The good news is that we can get that, by adding a single additional field to planFields: __typename. This provides to us the type name of whatever object it is that we are obtaining fields from. So, by changing planFields to:

fragment planFields on Plan {
  __typename
  id
  title
  startTime
  priority
  duration
  creationTime
}

…we now get output like this:

{
  "data": {
    "allTrips": [
      {
        "__typename": "Trip",
        "id": "2c494055-78bc-430c-9ab7-19817f3fc060",
        "title": "Vacation!",
        "startTime": "2017-12-20T13:14:00-05:00",
        "priority": "MEDIUM",
        "duration": 10080,
        "creationTime": "2017-02-19T15:21:58.547Z",
        "plans": [
          {
            "__typename": "Flight",
            "id": "319185bd-fab0-49e3-86ce-251d2aaa5d23",
            "title": "Flight to Chicago",
            "startTime": "2017-12-20T13:14:00-05:00",
            "priority": "HIGH",
            "duration": 150,
            "creationTime": "2017-02-19T15:21:58.547Z"
          },
          {
            "__typename": "Lodging",
            "id": "319185bd-fab0-49e3-86ce-251d2aaa5d23",
            "title": "House of Munster",
            "startTime": "2017-12-20T15:00:00-05:00",
            "priority": "MEDIUM",
            "duration": 9900,
            "creationTime": "2017-02-19T15:21:58.547Z"
          }
        ]
      },
      {
        "__typename": "Trip",
        "id": "e323fed5-6805-4bcf-8cb6-8b7a5014a9d9",
        "title": "Business Trip",
        "startTime": "2018-01-14T11:45:00-05:00",
        "priority": "HIGH",
        "duration": 4320,
        "creationTime": "2017-02-19T15:21:58.547Z",
        "plans": [
          {
            "__typename": "Flight",
            "id": "d40eb2e7-3211-422e-858c-403cbe3fa680",
            "title": "Flight to Denver",
            "startTime": "2018-01-14T11:45:00-05:00",
            "priority": "HIGH",
            "duration": 257,
            "creationTime": "2017-02-19T15:21:58.547Z"
          },
          {
            "__typename": "Lodging",
            "id": "e28a591b-cdc9-4328-9e79-9e4ed60ae7d2",
            "title": "Hotel Von",
            "startTime": "2018-01-14T15:00:00-05:00",
            "priority": "MEDIUM",
            "duration": 4140,
            "creationTime": "2017-02-19T15:21:58.547Z"
          }
        ]
      }
    ]
  }
}

Because we added __typename to planFields, everywhere we are getting fields from a Plan — both the Trip and its plans — we get a __typename telling us how to interpret the data. So, now we have a positive indicator of what is a Flight and what is Lodging, instead of having to infer the type from the available fields.

Note that you can alias __typename, just as you can alias any other sort of field:

fragment planFields on Plan {
  type: __typename
  id
  title
  startTime
  priority
  duration
  creationTime
}

Now, we would get the type as a type field in the JSON, rather than as __typename.

Note that Apollo-Android does not allow you to retrieve the __typename field. Apollo-Android uses that internally for type resolution — this is how Apollo-Android can create Flight and Lodging objects correctly. However, as a result, if you try to add __typename yourself to a query, your build will fail. However, your result objects (e.g., AllTrip) have a __typename() method that will return the __typename value as retrieved by Apollo-Android.

Introspection Beyond the Type Name

Getting the type name may be something of use to many apps (or, at least those not using Apollo-Android).

Introspection of a GraphQL server beyond the type name is something that a few apps will use, mostly in the area of development tools:

Let’s see how those sorts of tools can examine the server’s GraphQL schema via introspection queries.

Requesting the Roots

In the GrapiQL for the public demo GraphQL server (https://graphql-demo.commonsware.com/0.2/graphql), try entering the following query:

{
  __schema {
    queryType {
      name
    }
    mutationType {
      name
    }
  }
}

Anything beginning with __ is part of the introspection system. In particular, querying the __schema does what it says: it queries the schema to find out what is inside of it.

Here, we are requesting two fields: queryType and mutationType. Those are the GraphQL types that have been designated by the server as defining the root fields available for queries and mutations, respectively.

A typical implementation will have those types named Query and Mutation, respectively, which we get back by asking for the name fields of those types:

{
  "data": {
    "__schema": {
      "queryType": {
        "name": "Query"
      },
      "mutationType": {
        "name": "Mutation"
      }
    }
  }
}

Listing the Types

You can get a roster of all the registered types in the schema by querying on the types field:

{
  __schema {
    types {
      name
    }
  }
}

This will return more than you might expect, though:

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "Query"
        },
        {
          "name": "Trip"
        },
        {
          "name": "Plan"
        },
        {
          "name": "ID"
        },
        {
          "name": "String"
        },
        {
          "name": "Note"
        },
        {
          "name": "Comment"
        },
        {
          "name": "Link"
        },
        {
          "name": "Priority"
        },
        {
          "name": "Int"
        },
        {
          "name": "Mutation"
        },
        {
          "name": "TripInput"
        },
        {
          "name": "__Schema"
        },
        {
          "name": "__Type"
        },
        {
          "name": "__TypeKind"
        },
        {
          "name": "Boolean"
        },
        {
          "name": "__Field"
        },
        {
          "name": "__InputValue"
        },
        {
          "name": "__EnumValue"
        },
        {
          "name": "__Directive"
        },
        {
          "name": "__DirectiveLocation"
        },
        {
          "name": "Lodging"
        },
        {
          "name": "Flight"
        }
      ]
    }
  }
}

The registered types can be divided into three groups:

In the JSON above — pulled from the GraphQL demo server — the following types are standard GraphQL ones:

Those appear in the output because they are directly referenced by the GraphQL schema used by the server. Other stock types, such as Float, do not appear. And, given that GraphQL is type-safe, any unused type is unusable — there is nothing in the server’s schema that can accept a Float.

We can get more information about these types by adding in two more fields to our query, defined on __Type: kind and description:

{
  __schema {
    types {
      name
      kind
      description
    }
  }
}

The description is an optional comment about what the type is for. The kind indicates the general type of GraphQL type that this is: SCALAR, OBJECT, ENUM, etc.

The GraphQL demo server will return something akin to:

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "Query",
          "kind": "OBJECT",
          "description": "These are the available queries, representing data that  we can retrieve from this server"
        },
        {
          "name": "Trip",
          "kind": "OBJECT",
          "description": "Represents a collection of plans encompassing some trip to somewhere for something"
        },
        {
          "name": "Plan",
          "kind": "INTERFACE",
          "description": ""
        },
        {
          "name": "ID",
          "kind": "SCALAR",
          "description": "The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `\"4\"`) or integer (such as `4`) input value will be accepted as an ID."
        },
        {
          "name": "String",
          "kind": "SCALAR",
          "description": "The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text."
        },
        {
          "name": "Note",
          "kind": "UNION",
          "description": ""
        },
        {
          "name": "Comment",
          "kind": "OBJECT",
          "description": ""
        },
        {
          "name": "Link",
          "kind": "OBJECT",
          "description": ""
        },
        {
          "name": "Priority",
          "kind": "ENUM",
          "description": ""
        },
        {
          "name": "Int",
          "kind": "SCALAR",
          "description": "The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1. "
        },
        {
          "name": "Mutation",
          "kind": "OBJECT",
          "description": ""
        },
        {
          "name": "TripInput",
          "kind": "INPUT_OBJECT",
          "description": ""
        },
        {
          "name": "__Schema",
          "kind": "OBJECT",
          "description": "A GraphQL Schema defines the capabilities of a GraphQL server. It exposes all available types and directives on the server, as well as the entry points for query, mutation, and subscription operations."
        },
        {
          "name": "__Type",
          "kind": "OBJECT",
          "description": "The fundamental unit of any GraphQL Schema is the type. There are many kinds of types in GraphQL as represented by the `__TypeKind` enum.\n\nDepending on the kind of a type, certain fields describe information about that type. Scalar types provide no information beyond a name and description, while Enum types provide their values. Object and Interface types provide the fields they describe. Abstract types, Union and Interface, provide the Object types possible at runtime. List and NonNull types compose other types."
        },
        {
          "name": "__TypeKind",
          "kind": "ENUM",
          "description": "An enum describing what kind of type a given `__Type` is."
        },
        {
          "name": "Boolean",
          "kind": "SCALAR",
          "description": "The `Boolean` scalar type represents `true` or `false`."
        },
        {
          "name": "__Field",
          "kind": "OBJECT",
          "description": "Object and Interface types are described by a list of Fields, each of which has a name, potentially a list of arguments, and a return type."
        },
        {
          "name": "__InputValue",
          "kind": "OBJECT",
          "description": "Arguments provided to Fields or Directives and the input fields of an InputObject are represented as Input Values which describe their type and optionally a default value."
        },
        {
          "name": "__EnumValue",
          "kind": "OBJECT",
          "description": "One possible value for a given Enum. Enum values are unique values, not a placeholder for a string or numeric value. However an Enum value is returned in a JSON response as a string."
        },
        {
          "name": "__Directive",
          "kind": "OBJECT",
          "description": "A Directive provides a way to describe alternate runtime execution and type validation behavior in a GraphQL document.\n\nIn some cases, you need to provide options to alter GraphQL's execution behavior in ways field arguments will not suffice, such as conditionally including or skipping a field. Directives provide this by describing additional information to the executor."
        },
        {
          "name": "__DirectiveLocation",
          "kind": "ENUM",
          "description": "A Directive can be adjacent to many parts of the GraphQL language, a __DirectiveLocation describes one such possible adjacencies."
        },
        {
          "name": "Lodging",
          "kind": "OBJECT",
          "description": ""
        },
        {
          "name": "Flight",
          "kind": "OBJECT",
          "description": ""
        }
      ]
    }
  }
}

Collecting the Fields

The fields for a type can be obtained by querying the fields field on the __Type:

{
  __schema {
    types {
      name
      fields {
        name
      }
    }
  }
}

This just gives us each field’s name (here, just showing Trip for brevity):

{
  "name": "Trip",
  "fields": [
    {
      "name": "id"
    },
    {
      "name": "startTime"
    },
    {
      "name": "title"
    },
    {
      "name": "notes"
    },
    {
      "name": "creationTime"
    },
    {
      "name": "updateTime"
    },
    {
      "name": "priority"
    },
    {
      "name": "duration"
    },
    {
      "name": "plans"
    }
  ]
}

This, of course, just gives us the field name. We can also ask for its description, but we really need more to go on than those.

Field Types

A field has a type field, that we can use to find out the type of that field… at least partially:

{
  __schema {
    types {
      name
      fields {
        name
        type {
          name
          kind
        }
      }
    }
  }
}

That gives us the following Trip result:

{
  "name": "Trip",
  "fields": [
    {
      "name": "id",
      "type": {
        "name": null,
        "kind": "NON_NULL"
      }
    },
    {
      "name": "startTime",
      "type": {
        "name": null,
        "kind": "NON_NULL"
      }
    },
    {
      "name": "title",
      "type": {
        "name": null,
        "kind": "NON_NULL"
      }
    },
    {
      "name": "notes",
      "type": {
        "name": null,
        "kind": "LIST"
      }
    },
    {
      "name": "creationTime",
      "type": {
        "name": null,
        "kind": "NON_NULL"
      }
    },
    {
      "name": "updateTime",
      "type": {
        "name": null,
        "kind": "NON_NULL"
      }
    },
    {
      "name": "priority",
      "type": {
        "name": null,
        "kind": "NON_NULL"
      }
    },
    {
      "name": "duration",
      "type": {
        "name": null,
        "kind": "NON_NULL"
      }
    },
    {
      "name": "plans",
      "type": {
        "name": null,
        "kind": "NON_NULL"
      }
    }
  ]
}

The catch is that all of these types are not-null or list types. GraphQL handles this via type decoration, wrapping a type in a NOT_NULL or LIST type. For those, ofType unwraps the next layer down:

{
  __schema {
    types {
      name
      fields {
        name
        type {
          name
          kind
          ofType {
            name
            kind
          }
        }
      }
    }
  }
}

However, that will be insufficient. A non-null list of non-null types requires four levels of nesting (the original type and three ofType fields within it):

{
  __schema {
    types {
      name
      fields {
        name
        type {
          name
          kind
          ofType {
            name
            kind
            ofType {
              name
              kind
              ofType {
                name
                kind
              }
            }
          }
        }
      }
    }
  }
}

This gives us the following details for Trip:

{
  "name": "Trip",
  "fields": [
    {
      "name": "id",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "ID",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "startTime",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "title",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "notes",
      "type": {
        "name": null,
        "kind": "LIST",
        "ofType": {
          "name": null,
          "kind": "NON_NULL",
          "ofType": {
            "name": "Note",
            "kind": "UNION",
            "ofType": null
          }
        }
      }
    },
    {
      "name": "creationTime",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "updateTime",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "priority",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "Priority",
          "kind": "ENUM",
          "ofType": null
        }
      }
    },
    {
      "name": "duration",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "Int",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "plans",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": null,
          "kind": "LIST",
          "ofType": {
            "name": null,
            "kind": "NON_NULL",
            "ofType": {
              "name": "Plan",
              "kind": "INTERFACE"
            }
          }
        }
      }
    }
  ]
},
{
  "name": "Plan",
  "fields": [
    {
      "name": "id",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "ID",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "startTime",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "title",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "notes",
      "type": {
        "name": null,
        "kind": "LIST",
        "ofType": {
          "name": null,
          "kind": "NON_NULL",
          "ofType": {
            "name": "Note",
            "kind": "UNION",
            "ofType": null
          }
        }
      }
    },
    {
      "name": "creationTime",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "updateTime",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "String",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    },
    {
      "name": "priority",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "Priority",
          "kind": "ENUM",
          "ofType": null
        }
      }
    },
    {
      "name": "duration",
      "type": {
        "name": null,
        "kind": "NON_NULL",
        "ofType": {
          "name": "Int",
          "kind": "SCALAR",
          "ofType": null
        }
      }
    }
  ]
}

(in case you had not already determined this… introspection responses can be rather verbose)

That type-unwrapping GraphQL snippet will be needed elsewhere, so you can always define it as a fragment:

{
  __schema {
    types {
      name
      fields {
        name
        type {
          ...TypeDesc
        }
      }
    }
  }
}

fragment TypeDesc on __Type {
  name
  kind
  ofType {
    name
    kind
    ofType {
      name
      kind
      ofType {
        name
        kind
      }
    }
  }
}

Field Arguments

You can find out about arguments of fields via the args field on __Type:

{
  __schema {
    types {
      name
      fields {
        name
        args {
          name
          description
          type {
            ...TypeDesc
          }
          defaultValue
        }
      }
    }
  }
}

fragment TypeDesc on __Type {
  name
  kind
  ofType {
    name
    kind
    ofType {
      name
      kind
      ofType {
        name
        kind
      }
    }
  }
}

(using the TypeDesc fragment from earlier)

Each argument has its own name, description, and type, where the type follows the same structure as does the type of the field itself. An argument also has a defaultValue, if one is part of the schema.

So, for example, the GraphQL demo server’s Query type has two fields, each with one argument:

{
  "name": "Query",
  "fields": [
    {
      "name": "allTrips",
      "args": []
    },
    {
      "name": "getTrip",
      "args": [
        {
          "name": "id",
          "description": "",
          "type": {
            "name": null,
            "kind": "NON_NULL",
            "ofType": {
              "name": "ID",
              "kind": "SCALAR",
              "ofType": null
            }
          },
          "defaultValue": null
        }
      ]
    },
    {
      "name": "findTrips",
      "args": [
        {
          "name": "searchFor",
          "description": "",
          "type": {
            "name": null,
            "kind": "NON_NULL",
            "ofType": {
              "name": "String",
              "kind": "SCALAR",
              "ofType": null
            }
          },
          "defaultValue": null
        }
      ]
    }
  ]
}

Field Deprecation Status

Fields can be marked as “deprecated” in the server’s schema. This means that while the field still exists and can be used, it may be removed in the future, and so clients should try to move off of it and onto whatever the replacement is.

When you query on __Type, by default, deprecated fields are not returned in the result set. However, the fields field takes an optional includeDeprecated argument, which if you set it to be true, will cause the query to return deprecated fields as well:

{
  __schema {
    types {
      name
      fields(includeDeprecated: true) {
        name
        args {
          name
          description
          type {
            ...TypeDesc
          }
          defaultValue
        }
      }
    }
  }
}

fragment TypeDesc on __Type {
  name
  kind
  ofType {
    name
    kind
    ofType {
      name
      kind
      ofType {
        name
        kind
      }
    }
  }
}

However, the results will not tell you anything regarding the deprecation status… unless you query for that too. You can query for isDeprecated and deprecationReason for the fields field. isDeprecated will be true or false depending upon the deprecation state, while deprecationReason will be some sort of human-readable explanation of why the field was deprecated, or null if there is no stated reason or if the field is not deprecated.

The GraphQL demo server does not have any deprecated fields (yet). As a result, if you execute this document:

{
  __schema {
    types {
      name
      fields(includeDeprecated: true) {
        name
        args {
          name
          description
          type {
            ...TypeDesc
          }
          defaultValue
        }
        isDeprecated
        deprecationReason
      }
    }
  }
}

fragment TypeDesc on __Type {
  name
  kind
  ofType {
    name
    kind
    ofType {
      name
      kind
      ofType {
        name
        kind
      }
    }
  }
}

…you will see that isDeprecated is consistently false and deprecationReason is consistently null.

Type-Specific Results

Everything cited above is common to all types. Some types will have additional information that you can retrieve via introspection queries, such as:

Assembling GraphQL