Sitecore Experience Management

GraphQL

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 has these features:

  • It is front-end driven. The GraphQL protocol is aimed at front-end development: for web apps, for PWAs (progressive web apps), and mobile apps.

  • It is efficient. GraphQL returns only the requested data from a query. This eliminates data over-fetching, saves bandwidth, and improves performance. You can use advanced features like query batching and automatic persisted queries to reduce bandwidth usage needs even further.

  • It is strongly typed and schema-driven. The built-in schema introspection makes GUI query authoring tools, self-documentation, static analysis, and API mocking capabilities possible.

  • GraphQL queries are graph traversals. This enables very expressive queries that you would need a large number of requests to perform through a REST API.

  • It has a large ecosystem. The GraphQL community is large and there are many useful tools available.

GraphQL is appropriate when you need a production-grade API to power a frontend. 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 very good tutorials out there on how to use and learn GraphQL, including Apollo Launchpad that lets you create a GraphQL server and query it right in a browser.

 

Sitecore GraphQL concepts

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

You define endpoints that have specific 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 features such as 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 it has been created by schema providers. This enables scenarios such as allowing a standard item graph type to have new analytics properties added to it by an analytics extender, or integrating data from a CRM system or another REST service provider into an item field.

Sitecore GraphQL supports authentication (via standard auth cookies), as well as 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.

Sitecore GraphQL is optimized for speed. There are also performance metrics that can be used to analyse performance problems on a per-field basis when enabled.

The GraphQL query editor is built in to Sitecore GraphQL endpoints for authoring of queries (with code completion) and review of API documentation. The GraphQL type system knows about Sitecore templates, so you can 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 strong typed access to, for example, the src and width of an image field in addition to its value.