If you were at the 2018 Sitecore Symposium, you may have attended a talk I co-presented with Bryan Mills. During the presentation, I described what GraphQL actually is and how Sitecore exposes it's GraphQL implementation. I wanted to go into a little more detail here though, where I can take all the time I need.

What is GraphQL?

GraphQL probably has the most concise description of what GraphQL is on their homepage. It's offensively good, but what it boils down to is that GraphQL is a query language for API's. GraphQL services provide typings that are descriptive and understandable definitions of the data in the API.

The query language itself allows developers to query only the fields they'd like to receive back and nothing more. A response from a GraphQL query will be the same shape as the request as well, which is a really unique feature. This field selection feature is one of the biggest game changing features. As a backend developer, I'm really used to having to modify my endpoints to add new fields when they become required for some new functionality that's being built. Field selection allows the front end developer to do this on their own though. If a new field was added on a Sitecore template and the developer wanted the field in the response, they would be able to just add this new field to their query and the server would start returning it. This essentially allows front end developers to build web services on demand.

How Sitecore Exposes GraphQL

GraphQL is currently bundled with Sitecore JSS. Sitecore's GraphQL implementation is designed to be generic, allowing for customization.

To get started using GraphQL, you just need to install the Sitecore JSS package and define at least one endpoint. Defining an endpoint is as easy as dropping a configuration file in your App_Config/Include directory. There's an example configuration file available on the GraphQL Overview page on the Sitecore JSS site.

There are some configuration properties that you can customize. For instance, in the linked configuration file above is secured to only allow users that are authenticated with Sitecore to be able to query this endpoint with this line:

<security ref="/sitecore/api/GraphQL/defaults/security/systemService" />

We wanted something we could embed though, so we used a different, built in security mode which allows API tokens to be used for authentication instead. That security mode can be configured by changing that security line to this:

<security ref="/sitecore/api/GraphQL/defaults/security/publicService" />

API tokens can be added by creating a new API token item in the Core database in Sitecore at this path: /sitecore/system/Settings/Services/API Keys.

Additionally, Sitecore exposes an optional interface for writing and testing queries. The interface is based on GraphiQL and is extremely useful for exploring the endpoint and testing out queries. You can enable this interface by setting compilation to true in your web.config and then accessing the endpoint address you configured in your GraphQL configuration file with "/ui" at the end of it.

So if I had an endpoint defined here: http://<local>/sitecore/api/graph/items/master then the interface would be made available here: http://<local>/sitecore/api/graph/items/master/ui.

Hopefully that's enough to get you started with working with Sitecore's GraphQL implementation. In my next post, I'll show some of the queries we built during the demo portion of the talk and how we select items and template fields directly.