Sitecore GraphQL API

Abstract

Describes how to set up and start using GraphQL with Sitecore

The Sitecore GraphQL API is a generic GraphQL service platform on top of Sitecore. It hosts your data and presents it through GraphQL queries. The API supports real-time data using GraphQL subscriptions.

GraphQL is appropriate when you need a production-grade API to power a front end. Compared to traditional REST APIs, GraphQL is significantly more maintainable, far more easily discoverable and queryable (thanks to built-in GUI tools), much more bandwidth-efficient, and much more powerful.

There are excellent tutorials available on how to use and learn GraphQL.

Sitecore GraphQL concepts

The Sitecore GraphQL API implements the GraphQL standard but has some Sitecore-specific details:

You define endpoints with absolute URLs. These endpoints host a GraphQL schema (a strongly typed graph definition). This schema is comprised of one or more schema providers (for example, ContentSchemaProvider or CustomersCrmSchemaProvider). These endpoints understand the GraphQL language. Unlike REST APIs, there is a formal request and response format. Therefore, GraphQL endpoints are all serviced by a single controller, and no code is required to define a new endpoint. This also enables request batching (multiple queries in a single HTTP request) to reduce network traffic.

Each endpoint has its own isolated configuration, so endpoints can be isolated from any other endpoints’ configuration to increase reliability. You can also extend the whole schema with extenders that modify and add to the GraphQL schema for an endpoint after schema providers have created it. This enables scenarios such as allowing a standard item graph type to have new analytics properties added by an analytics extender, or integrating data from a CRM system or another REST service provider into an item field.

Sitecore GraphQL supports authentication (through standard authentication cookies) and attribution and impersonation using SSC API keys. You can use custom authorization routines. Content endpoints can disable specific operations, so, for example, a mutation-free read-only content endpoint is possible.

The GraphQL query editor is built into Sitecore GraphQL endpoints to author queries (with code completion) and review of API documentation. The GraphQL type system knows about Sitecore templates. You can therefore create and validate strongly typed queries against real fields. Template changes are updated in real-time. Template fields are also mapped to GraphQL types, so you get strongly typed access to, for example, the src and width of an image field in addition to its value.