Introspection with GraphQL

GraphQL is a query language based on a type system. GraphQL types define what objects are supported, what fields are associated with an object, and what can be queried and how, which is all defined by the GraphQL schema. To be able to use GraphQL APIs effectively, it is essential to have a good understanding of Supply Chain Intelligence Suite data model.

About this task

A great way to learn Supply Chain Intelligence Suite data model schema is through using GraphQL introspection. Schema introspection can help whenever you have a question about any part of the schema, such as what objects are defined, what fields are associated with a type, what are the values of an enumeration, what kind of queries are supported, and what parameters can be used for a query.

You learn the following tasks:

• How to find all the supported types, such as objects, interfaces, enum.
• How to find more details of each type, such as fields for an object or values of an enum.
• Which queries are supported and the query details, such as parameters.
• Which mutations are supported.
• How to construct a GraphQL query based on introspection results.

You can use documentation explorer in GraphiQL.

The GraphiQL tool uses introspection logic to build an interactive schema explorer in the UI. Navigate to the GraphiQL interface by pasting this URL in your browser:

https://api.ibm.com/infohub/run/graph/na

And note the Docs link:

When you click the Docs link, GraphiQL sends a schema introspection request to the GraphQL API, then parses the response into a document object model (DOM) that you can then navigate. The Documentation Explorer is then rendered, along with a list of the top-level objects in the model, which in this example are query and mutation.

In this view, you can drill down to explore all objects and their attributes. For example, after drilling into query, the view shows the BusinessEventInput value of the eventParams attribute for the query:

1. Introspect all types that are defined in the schema in the GraphQL visual editor.
   1. Navigate to the GraphiQL visual editor by entering the following URL in a browser:
      https://api.ibm.com/infohub/run/graph/na
   2. Paste the following GraphQL query into the left side of the editor, and click Run.

      query {
       __schema {
      	    types {
      		  name
      		  description
      		  kind
      		}
      		queryType {
      		  fields {
      			name
      			description
      		  }
      		}
         }
       }

      After the query is completed, you can see the query response on the right side of the editor. Look through the response and find some examples of OBJECT, INTERFACE, and ENUM. OBJECT types are the foundation of GraphQL APIs. Each OBJECT has fields, which expose data and can be queried by name. INTERFACEs are list of fields, which might be implemented by OBJECT types. ENUM types are sets of discrete values.

      
   3. Navigate to the bottom of the response and view the list of queries that are supported.
   4. Optional: In the GraphiQL visual editor, use the link on the upper right corner to inspect the schema definition.
2. Run the same GraphQL schema query in Insomnia.
   1. Open Insomnia, start a new request that is named Get Intelligence Suite schema info.
   2. Select POST from the list and enter the following URL:
      https://api.ibm.com/infohub/run/graph/na
   3. In the request body section, select GraphQL and copy and paste the same query from previous step into the QUERY box.
   4. Disable SSL certificate verification in Insomnia.
   5. Click Send and see the response in the response section of the request:
      The response must be identical to the one received in the preceding step.
3. Introspect the type details.
   1. Enter the following query into Insomnia:

        query {
          __type(name: "BusinessObjectsCursor") {
        	...FullType
          }
        }
      
        fragment FullType on __Type {
          kind
          name
          description
          fields(includeDeprecated: true) {
        	name
        	description
        	args {
        	  ...InputValue
        	}
        	type {
        	  ...TypeRef
        	}
        	isDeprecated
        	deprecationReason
          }
      
          inputFields {
        	...InputValue
          }
      
          interfaces {
        	...TypeRef
          }
      
          enumValues(includeDeprecated: true) {
        	name
        	description
        	isDeprecated
        	deprecationReason
          }
      
          possibleTypes {
        	...TypeRef
          }
        }
      
        fragment InputValue on __InputValue {
          name
          description
          type {
        	...TypeRef
          }
          defaultValue
        }
      
        fragment TypeRef on __Type {
          kind
          name
          ofType {
        	kind
        	name
        	ofType {
        	  kind
        	  name
        	  ofType {
        		kind
        		name
        		ofType {
        		  kind
        		  name
        		  ofType {
        			kind
        			name
        			ofType {
        			  kind
        			  name
        			  ofType {
        				kind
        				name
        			  }
        			}
        		  }
        		}
        	  }
        	}
          }
        }
      

   2. Examine the response that is received.
      BusinessObjectsCursor is an OBJECT type, which implements INTERFACE Cursor. It has three fields that are defined: edges, pageInfo, and totalCount. Field edges is a LIST of OBJECT BusinessObjectEdge. Knowing the INTERFACE can help to streamline queries with different OBJECT types in the responses.
      
   3. Replace the type name in the query with some other types that you picked in Step 1 or 2, run the query again, and check the responses to understand the type definitions.
4. Introspect types that are associated with an interface.
   Although the query shown in Step 3 can be used for any type, you might prefer simpler responses for specific types, such as INTERFACE or ENUM. You can get a clean list of OBJECTS that implement a specific INTERFACE. From GraphQL API client perspective, knowing the INTERFACE that an OBJECT implements can help to streamline query responses.
   1. Use the following query to find all OBJECTS that implements the same INTERFACE.

      query {
      __type(name: "Cursor") {
        name
        kind
        description
        possibleTypes {
          name
          kind
          description
        }
      }
      }  

      The response shows all the Cursor OBJECTS that are defined in Supply Chain Intelligence Suite.

      
   2. Pick another interface that you identified in Step 1 or 2, put it into the query, and run it to find all associated OBJECTs.
5. Introspect ENUM values.
   Supply Chain Intelligence Suite uses numerous ENUMs in the schema. An ENUM type defines a set of discrete values, for example, the Supply Chain Intelligence Suite ENUM type BusinessObjectType provides a list of all business objects that are defined in the schema. This step shows a query to get the value list of an ENUM.
   1. Copy and paste the following query into the tool of your choice and run the query.

      query {
      __type(name: "BusinessObjectType") {
        name
        kind
        description
        enumValues {
          name
          description
        }
      }
      }

      Check the result to see all object types that are listed under ENUM BusinessObjectType. This list shows which business data objects are supported in the API.

      
   2. Replace the type with another ENUM type that you picked in Step 1 or 2 and rerun the query to see the value list for that ENUM.
6. Introspect query definitions.
   All GraphQL queries that are supported are defined in a special type Query in the schema. You can use the query that is defined in Step 4 to get the related information.
   1. Run the following GraphQL query in Insomnia:

        query {
          __type(name: "Query") {
        	...QueryType
          }
        }
      
        fragment QueryType on __Type {
          fields {
        	name
        	description
        	type {
        		name
        		kind
        	}
        	args {
        	  name
        	  description
        	  type {
        		  name
        		  kind
        	  }
        	}
          }
        }

      Examine the response. Each supported query is shown as a field in the response. Currently, a total of four queries are defined in the schema. One of the queries is businessObjectEvents, which returns a BusinessEventCursor. This query can take five different parameters, one of which is advancedFilter of OBJECT type BooleanExp.

      
7. Introspect mutation definitions.
   Mutation is another schema type that defines all mutations that are supported by the API. Unlike GraphQL query APIs that are used to fetch data, GraphQL mutation APIs are provided to modify data on the server. Replace Query with Mutation in the query that is used in step 6, and check out all InforHub mutation definitions, that is, what kind of data manipulations are supported through the Supply Chain Intelligence Suite GraphQL API.
8. Construct your Supply Chain Intelligence Suite.
   You now know how to find all the supported types and how to find the details of each type. Sample queries were provided for INTERFACE, ENUM, Query, Mutation, which contain sufficient information to get started on constructing your first Supply Chain Intelligence Suite GraphQL query.
   1. Use the query in step 6 to find the definition of a query for businessRuleEvents.
   2. Use the query in step 3 to find the details of the response type.
   3. Use the query in step 3 to find the details of each query parameter.
   4. Based on the results of the preceding steps, construct a GraphQL query for businessRuleEvents.