Building Digital Experiences with GraphQL and an API-First CMS

Whether you’re searching for the answer to a question on the web or trying to recover a lost file you want the ability to type in exactly what you were looking for and get the precise response.

That ability to return a specific answer that many modern search engines offer is the same type of experience developers want when working with APIs.

Modern headless CMSs can often be classified as API-first CMSs allowing enterprises to deliver content to any channel they desire, developers to choose the frameworks that suit their needs best, and also make integrations with other tools in the tech stack much easier. 

To be a true API-first headless CMS, a content platform should also offer native GraphQL support. In this blog we’ll explain GraphQL, the differences with REST, and how to use GraphQL to build digital experiences. 

What Is GraphQL?

GraphQL is an open source query language for APIs and an API standard that offers an efficient and flexible alternative to REST. Originally developed and open-sourced by Facebook in 2012, the API has been maintained as a community open-source project since 2015. It is also language and database-agnostic. 

GraphQL uses declarative data fetching and mutations. A developer can specify exactly which data they need from an API. Rather than multiple endpoints that return fixed data structures, as in REST, a GraphQL server only exposes a single endpoint and responds with exactly the data a client wants.

REST vs GraphQL

REST is a popular method for sharing data from a server because it is simple, widely used, and works with standard web addresses (like HTTP) that most applications already use. When the concept of REST was introduced, client applicants were relatively simple and development wasn’t happening at the pace it is today. This made REST a good fit for most applications. 

However, the API landscape has shifted tremendously due to the following:

1. Increased mobile device usage creates a need for efficient data loading
2. A variety of different frontend frameworks and platforms
3. Faster development cycles and increased expectations for rapid feature development 

As a result, GraphQL has become a viable alternative and continued to increase in popularity. 

Some of the other differences between GraphQL and REST include:

Data Fetching

REST uses fixed endpoints with predefined responses. This means each endpoint returns a specific set of data, which can sometimes be more or less than what is needed. On the other hand, GraphQL uses a single endpoint and customizable queries so that clients can request exactly the data they need in a single request.

For example, see how a REST call is implemented for an example blog post implementation in Figure 1. 

Figure 1: Three (3) separate REST Calls for ID, POSTS, Followers

And now compare how an equivalent GraphQL call works in Figure 2. 

Figure 2: One (1) GraphQL Call with Filter

Flexibility

GraphQL is more flexible as it allows clients to specify the exact fields they need, resulting in more efficient data retrieval. In contrast, REST is less flexible because it returns full data sets from its fixed endpoints. This can lead to over-fetching, where more data than necessary is retrieved.

Performance

GraphQL is optimized for precise data fetching, as clients can tailor their queries to include only the necessary data, often reducing the number of requests needed. Performance in REST can be less optimal because it may involve over-fetching or under-fetching data. Clients might need to make multiple requests to get all the required data.

For example, an eCommerce company might rely on several systems including a PIM, CMS, and an eCommerce system that handles inventory and pricing data. To display the correct product information on the eCommerce website this might require multiple API calls made to all of these systems when using REST. With GraphQL a single request can be made instead. 

Use Cases

REST is suitable for simple, standard data operations where fixed endpoints and predefined responses are sufficient. GraphQL, however, is ideal for complex queries and data-fetching scenarios. 

GraphQL for Content-Driven Multichannel Digital Experiences

When managing content and digital experiences across multiple channels it becomes apparent that each channel type is unique. Some channels lend themselves to displaying different content compared to others and businesses need one API that can efficiently meet those needs.

With REST, developers need to manage multiple APIs and if a new channel is added they need to revisit what information their API provides. On the other hand, GraphQL provides a single API that can meet various needs.

Additionally, GraphQL offers another benefit for developers as it follows a standardized set of principles. With REST, each system has its own API and developers need to familiarize themselves and relearn styles every time they encounter a new API. 

With GraphQL as long as a developer knows GraphQL it will be the same from system to system, providing added flexibility and helping to increase speed to market for launching digital experiences. 

Using GraphQL in CrafterCMS

CrafterCMS provides built-in support for GraphQL to query content in any project without writing additional code. A GraphQL schema is generated independently for each project based on the content-type configuration created using Crafter Studio (the CMS UI app), and the schema is automatically updated after any change is detected.

In addition, GraphiQL is a simple, open source GraphQL client that is embedded into Crafter Studio that enables you to run GraphQL queries and explore the schema documentation for a project without needing any other tool.

Additionally, CrafterCMS’s GraphQL server provides:

• Automatic generation of schema and associated resolvers for all managed content
• Optimization and retrieval of content types by GraphQL requests
• Iteratively indexing all content type metadata as content types change (Lifecycle management)
• Single query retrieval of complex types and associated metadata
• Creates and manages advanced filter and transformational GraphQL solutions
• Automatic discovery and associated documentation of all managed content

CrafterCMS built a content platform with an optimized GraphQL server so that developers wouldn’t have to.

CrafterCMS: API-First Content Platform for GraphQL Developers

CrafterCMS is an API-first CMS that offers both REST and GraphQL API support. This provides developers with the flexibility to choose the right API for their specific use cases. Additionally, CrafterCMS offers additional features not only for developers but for content authors and operations personnel as well. 

• Ease of Use For Content Authors: Content teams can leverage user-friendly tools to create, update, and publish to any digital channel. This includes drag/drop experience building, WYSIWYG content editing, multi-channel preview, and more for composing digital experiences.
• Freedom For Developers: Developers can create websites and apps with an open source, Git-based headless CMS using any UI framework on the frontend including React, Vue, and Angular, as well as built-in Freemarker templating for HTML sites. Additionally, they can extend the backend with Groovy or JavaScript including Node.js and Next.js.
• Efficient Operations: Operations teams can choose from SaaS or self-hosted/self-managed options. They can also benefit from enterprise-grade monitoring, security, and compliance, combined with a small high-performance footprint that scales elastically and globally.

Learn more about using GraphQL in CrafterCMS in our webinar: Building Multi-Channel Digital Experiences with GraphQL.