Introduction
GraphQL Explorer is an integrated GraphQL testing tool. The advantage to having it built in is you can test faster and quicker without having to install additional packages and maintain credentials as you test.
You can find the GraphQL Explorer by navigating to All > System Web Services > GraphQL > GraphQL Explorer. (Although I like to use the navigation filter and type QL E).
After the GraphQL Explorer is displayed, you'll notice it differs quite a bit from the REST API Explorer (if you've used that.) That's because it is based on the popular GraphiQL. The large window on the left is for entering your queries and the window on the right displays the results (see Figure 1.)
Figure 1: A typical GraphQL Explorer
Between the left and right windows is a toolbar. The top icon is the Execute Query button. It submits your query to the instance. After processing the query, the response is displayed on the right.
NOTE: If you are writing an app or API to process the response, most responses return a 200 OK. Be sure to process the response looking for errors rather than relying on the HTTP response code.
Below the Execute Query button is the Prettify Query icon. Clicking this icon cleans up the formatting of your query on the left. This is particularly handy if you are copying and pasting text from another source.
The third icon is Merge Fragments. If you have fragments defined in your query, this icon replaces the references with the fragments themselves. Personally, I haven't found that much use for this button as I consider fragments more like macros to decrease repeated content. This seems to undo that idea. I'd be interested to hear if someone has a legitimate use for merging framents.
The final icon is used to copy the query in the left window to the copy/paste buffer. This is similar to selecting all the text (Cmd-A/Ctrl-A) and then copying it (Cmd-C/Ctrl-C).
Figure 2: The center toolbar
Introspection
A big advantage of GraphQL is that the server (or ServiceNow instance) defines a schema of what is (and is not) allowed by the client making the request. To decrease the need for documentation on the API itself, the GraphQL Explorer use introspection to give you visibility to the API's details using the Document icon in the upper left (see Figure 3.) With a few simple clicks you can identify queries and mutations, available properties (or fields), and their specific data types.
System properties
You may notice nothing appears when you click the documentation icon. By default, introspection is turned off. There are two main system properties related to the GraphQL Explorer and its introspection. The first
glide.graphql.introspection_enabled
is a boolean that enables (true) or disables (false) introspection to the APIs defined in the GraphQL API (sys_graphq_schema) table.
The second property,
glide.graphql.glide_record_schema.introspection_enabled
is also a boolean nd enables (true)/disables (false) the introspection for the built-in GlideRecord Schema.
Note: Enabling the GlideRecord property can make the GraphQL Explorer slow to load. If you are the type to bring up the GraphQL Explorer in the morning and stay there all day, you may be OK with the extra minute or so to load the GraphQL Explorer, but is everyone else on your instance OK with that level of delay?
Figure 3: The documentation icon uses introspection to display details of the available APIs.
History
As you create and test queries, the system automatically saves a history of them. These are easily accessible from the history icon (show in Figure 4.)
Figure 4: The history icon makes it easy to recall previous queries.
Variables and Headers
If are you testing queries that require variables, you can click the Variables tab in the lower left (show expanded in Figure 5) and enter JSON with your name/value pairs in the window provided.
Similarly, you can click the Headers tab and enter JSON corresponding to the header name/value pairs needed. For example:
{
"Accept" : "application/json"
}
Figure 5: GraphQL Explorer supports variables and headers.
Cool stuff in the lower left corner
There are a few more icons worth noting in the lower left corner. The top-most is a circular icon (see Figure 6). When clicked, this re-reads the schemas to update data used for introspection. This is handy if you are creating an API and added some new functionality or changed a field type, but do not want to go through the hassle of exiting and restarting the GraphQL Explorer.
Figure 6: Other useful options can be found in the lower left.
The middle icon produces a list of keyboard shortcuts when clicked. Being a keyboard shortcut advocate myself, I invite you to use them to improve your development times.
Figure 7: Keyboard shortcuts are available and can improve efficiency.
The bottom-most icon produces a few configuration options like dark-mode when clicked.
Tabs
As you get more advanced, you may be debugging multiple queries at the same time. This can be done by locating the + icon next to the words GraphQL Explorer in the upper right corner of the screen (see Figure 8). Clicking it produces a second tab in the left side of the window and a + icon next to the list of tabs (use that one to creat more tabs because the one next to GraphQL Explorer is no longer there. I know, kind of obvious, but I'm trying to be complete here.)
Figure 8: Click the + to create another tab to work on multiple queries.
Here's the part that baffled me at first. I wanted to change the name of the query, but clicking it didn't allow me to edit. It turns out that the GraphQL Explorer gets the tab name from the query name (see Figure 9). If you use the keyword query (which is optional) or mutation, the tab name is populated. If you do not use query, the tab is displayed as <untitled>.
Figure 9: Tab names come from the query names in the left window.
Learn more
Want to learn more about GraphQL? Take the free online, hands-on lab CreatorCon at Knowledge 23.
Docs
2 Comments
