SUGCON 2019: Fun with Sitecore JSS, Exploring GraphQL Slide Notes

Weren't able to attend my SUGCON talk on Sitecore JSS and GraphQL? Here's a description of some of the things that were discussed throughout the slide portion of the presentation. You can download the slides from the SUGCON.EU site.

This post will focus on the substance of the slide deck, but I will say... you did miss me professing my love for GraphQL.

Defining GraphQL

We kicked off the presentation by going through the description that is on the GraphQL homepage and breaking down the individual pieces.

The first part of that definition is:

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data.

What this first part really says to me is that GraphQL is two things, a run time and a query language.

As for the run time, we are fortunate that Sitecore has built this part out for us. It's currently shipping with Sitecore JSS and there's no massive migration of data or duplicate database to get started with it. Getting the run time up and running is just a package install and defining an endpoint away. It leverages your existing databases and templates.

The second part is a query language. The syntax looks a lot like JSON if you're looking at it for the first time but has differences. Requests and responses are roughly the same shape. That is to say the general structure of your request will essentially be mirrored in your response, but with values populated. This leads to predictable responses from the endpoint. Requests can and should be parameterized. The JSS documentation call this out specifically. You should be leverage parameters and libraries to build out your queries and not building them out by hand by appending a bunch of strings together.

At this point we reviewed some queries from this article titled "The Anatomy of a GraphQL Query".

There are two components we reviewed:

• Fields: These are the things we're selecting in our query. In this example, we're selecting the name and height fields on the human field.
• Arguments: Fields can accept arguments, which feels awkward coming from a C# background, but it's allowed in GraphQL. In this example, we're passing in the id of "1000" and a unit of measure for the height field.

The above query is a bit of the short hand version of writing a query. This example query is ultimately requesting a single human of id "1000" and is selecting the name and height fields off of this human object.

We then explored a more complex query type that contains some new components:

We talked about the additional components in this example:

• Operation Type: This is the type of operation that we're performing. We're selecting data in this example so the operation type is query. Other valid operation types including subscription and mutation. Subscriptions allow you to listen to a particular operation via a web socket. Mutations allow you to post content to the endpoint and cause a change.
• Operation Name: This is an optional field but you should use it. It should be descriptive because you'll see this name when requests are being made in your code and it could come in handy for debugging later.
• Variable Definitions: This are allows you to pass in variables from your code and those variables are passed through to your query so you can use them in arguments. Variables must be used or your query will error.

The second part of the GraphQL definition is:

GraphQL provides a complete and understandable description of the data in your API

GraphQL really does this through what are called typings. These typings are generated by the run-time and in the case of Sitecore, are our templates that are contained in the scope of our endpoint. A typing contains a name and a collection of fields, each field also has a name and a field type.

Typings can be inherited through interfaces and the Item typing you see in the GraphQL interface for Sitecore is actually an interface and all of the template typings implement it.

You can see what the Sitecore GraphQL endpoint is generating by navigating to: <graphql endpoint url>/schema. These are all the typings that Sitecore is generating for us.

Here is an example of two GraphQL typings:

The third part of the definition is:

Gives clients the power to ask for exactly what they need and nothing more

For this example, I want you to think of GraphQL as SQL for graphs. I provided an example SQL query and discussed what a hypothetical GraphQL query might look like to accomplish this same thing.

One thing they both have in common is that you can select only the fields you want to select and that's it. Also like SQL tables, GraphQL typings can change as well. Since we're only selecting a subset of fields, if we add new fields then the old query will just continue to work just like it did before. If the application wanted to update and take advantage of new functionality that was introduced in the future then they could, otherwise it will just continue to work.

The fourth part of the definition is:

And enables powerful developer tools.

The Sitecore JSS GraphQL endpoint has a built in interface built in. It's based on an open source library named GraphiQL and has a dark theme enabled by default. It's optional and will be really useful during local development but it's probably not something you want enabled on a production environment so the config file contains rules for disabling them in those situations.

The interface looks like this:

Conclusion

After these slides, we jumped over to some demos. I'll be covering the demos in a separate post. Hopefully this post has been a useful overview of GraphQL.