What is Introspection in GraphQL?
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"
},
.....
}
}
}
}Query Property Types
The next introspection query we are going to write is to query for the __type field. When querying for types we need to provide the name of the type we are querying for. I picked one of the types, RepositoryOwner returned from our previous query. In the query below we are looking for the description and name of all the fields for type RepositoryOwner.
query getRepositoryOwnerType {
__type(name:"RepositoryOwner") {
description
fields {
name
}
}
}Here is the JSON Response. You can see all the fields that are part of the type RepositoryOwner.
{
"data": {
"__type": {
"description": "Represents an owner of a Repository.",
"fields": [
{
"name": "avatarUrl"
},
{
"name": "id"
},
{
"name": "login"
},
{
"name": "repositories"
},
{
"name": "repository"
},
{
"name": "resourcePath"
},
{
"name": "url"
}
]
}
}
}Query Directives
From the __schema, we can also query for the directives supported by a GraphQL schema.
query getDirectives {
__schema {
directives {
name
description
}
}
}The JSON response shows that the GitHub schema supports three directives which are: include, skip and deprecated.
{
"data": {
"__schema": {
"directives": [
{
"name": "include",
"description": "Directs the executor to include this field or fragment only when the `if` argument is true."
},
{
"name": "skip",
"description": "Directs the executor to skip this field or fragment when the `if` argument is true."
},
{
"name": "deprecated",
"description": "Marks an element of a GraphQL schema as no longer supported."
}
]
}
}
}Conclusion
I hope you enjoyed learning about the GraphQL introspection system. If you are interested in further learning about GraphQL, you can checkout my GraphQL courses on Pluralsight:
Other resources:
I hope you enjoyed this article. See you again with more articles. If you liked this post, don’t forget to share it with your network. You can follow me on twitter @AdhithiRavi for more updates or if you have any questions.
This story was originally published at https://programmingwithmosh.com/
