Powering next-gen apps with GraphQL and headless CMS

In this article we will introduce two technologies in the field of modern web development: GraphQL and headless content delivery. We will then show how Optimizely can be used along with these technologies to deliver content decoupled to any touchpoint.

What is GraphQL?

GraphQL is an open-source query language and runtime for APIs that was developed by Facebook in 2012 and released as an open-source project in 2015. It is designed to enable clients to request only the data they need, making it more efficient and flexible than traditional approaches.

GraphQL allows clients to define the structure of the data they need from the client-side, and the server responds with only that data in a single request. This allows for quicker and more efficient data transfer as clients can avoid receiving data they don’t need.

GraphQL is not tied to any specific database or storage engine, and can be used with any language or framework. It has gained popularity in recent years as a more efficient and flexible alternative to REST APIs, particularly in large-scale applications or decoupled architectures where performance and scalability are important.

What is headless content delivery?

Headless content delivery refers to an approach in which the content management system (CMS) and the presentation layer are decoupled, meaning that the content can be delivered independently of the presentation layer.

In a traditional CMS, the content is created and stored in the CMS, and the presentation layer is tightly coupled with the CMS (often being served by the CMS itself), making it difficult to reuse content across multiple channels or devices.

With headless content delivery, the CMS is responsible for managing the content, while the presentation layer is handled by a separate application. The content is delivered via an API, which allows it to be consumed by any application or device, such as a website, mobile app, or IoT device.

This approach provides greater flexibility and agility in delivering content to various channels and devices, as the content can be consumed and presented in any way needed by that specific delivery channel. It also allows for easier updates and changes to the presentation layer, without affecting the underlying content or CMS platform.

Headless content delivery has gained popularity in recent years, as it enables organisations to provide unified experiences to their customers across various touchpoints.

Using GraphQL with Optimizely

The Optimizely Content Graph is a GraphQL implementation that enables developers and clients full access to content indexed from the Optimizely CMS. The Optimizely Content Graph was released in beta at the end of 2022, with the prospect of a full release coming soon.

Pictured: The Optimizely GraphiQL visual query builder and explorer interface found from within the CMS.

The visual query builder makes it much simpler for developers to extract just the right information they need for their implementations compared to other alternatives such as the Content Delivery API (more on that in the next section).

Pictured: An example query and search response for all pages of type “BlogPage” that are in the “en” (default English) locale.

Being able to explore the data schema and fix issues with the query in-context means developers no longer need specialised knowledge of Optimizely CMS content delivery norms to be able to effectively access content.

This means that front-end developers can become just as comfortable and productive (if not more so) than back-end developers when it comes to retrieving data and building integrations from the presentation layer or “head”.

Pictured: The same “BlogPage” search performed from the presentation layer front-end code, as used by a React application.

Developers can also use the standard REST API tools they are familiar with to access the same GraphQL content if they prefer to speed up development and testing.

Pictured: The same example “BlogPage” search performed using a REST API client, as screen developers are all too familiar with.

While the Content Graph is the newest offering from Optimizely, it is not the only way to headlessly drive content delivery using Optimizely CMS.

What is the Optimizely Content Delivery API?

Optimizely has another mechanism for headless content delivery released in 2018 using its Content Delivery API.

The Content Delivery API is a more traditional REST API that enables the same kind of headless content delivery use-cases on any touchpoint using JSON. Optimizely also offers a Javascript Content Delivery API SDK which enables developers to quickly integrate it in multiple front-end frameworks (React, Vue, Svelte, Angular etc).

Pictured: An example function that loads the website Start Page using the Content Definition API SDK as used in an React application.

Pictured: Developers can use the same REST API tooling to develop and test integrations with the Content Delivery API.

While the Content Delivery API is easy to work with, developers benefit from some expertise with Optimizely CMS to make sense of the data structure and models returned. The responses match those that back-end CMS developers have been working with for a very long time, so it can be beneficial for back-end and front-end to work together (at least initially).

As the Content Delivery API does not have the same goal as GraphQL, it does not have the same powerful search capabilities. Content retrieved can still be tailored to the needs of the implementation, and content can be filtered in a similar way, but this is an important difference between the two.

How to choose the right technology?

Choosing between GraphQL and the Content Delivery API as a general approach depends on several factors, including the specific needs of the project and the resources available to the team.

GraphQL is primarily a query language that allows developers to define precisely what data they need and receive that data in a single request. It is powerful for efficiently retrieving data, especially for complex or nested data structures.

On the other hand, the Content Delivery API provides a pre-built solution for delivering content from a CMS. It typically provides a simpler way to retrieve data than GraphQL but may have less flexibility in terms of the types of queries developers can make. However, it can be a faster and easier option to implement if you already have an existing CMS implementation in place.

Here are some factors to consider when choosing between GraphQL and the Content Delivery API:

• Project complexity: If your project involves complex data structures or requires flexible queries, GraphQL may be a better choice. If your project is a relatively straightforward page/block content retrieval, the Content Delivery API may be sufficient.

• Developer expertise: If you have developers who are experienced with GraphQL, it may be a better choice for your project. If you have developers who are more familiar with traditional REST APIs or Optimizely CMS back-end models, it may make more sense to use the Content Delivery API as a primary choice.

• Scalability: Scaling of the stand-alone GraphQL service is managed by Optimizely and not of concern to clients and their implementations. However, with the Content Delivery API scaling concerns would be part of the DXP hosting considerations as the API and CMS scale together.

• Stability: As the GraphQL Content Graph is hosted as a stand-alone service by Optimizely, a website built entirely upon it would be heavily impacted with any performance degradation or outages of the service - unless the implementation relies on Static Site Generation (SSR) but this is an advanced use-case. As the Content Graph is still in beta, we don’t yet know what this will look like in the future and which mitigations will be in place for outages. With the Content Delivery API as part of the CMS web-application itself, any degradation or outage of the CMS would also be felt from the Content Delivery API, similar to existing tightly coupled CMS implementations. However, traditionally, web-application hosting has been stable and more predictable.

Ultimately, the best choice depends on the specific needs and goals for the project.

Can we use both?

It does not have to be one or the other. Both can be used side by side to perform different functions.

For example, the Content Delivery API could be used for delivering the more “regular” content such as content from pages, blocks, and media, while the Content Graph could be used to power search results or more complex page layouts that pull in data from many sources simultaneously.

Using both will likely lead to maximising the strengths of each while avoiding some of the downsides. However, care should be taken as more planning and development expertise will be required to ensure the right tool is used for the right task throughout the life of the project.

Final thoughts

Optimizely is an incredibly powerful platform with a suite of products and services that can be customised to suit any business need, and with a continued drive towards a “modular” approach technologies like the Content Graph and Headless Content Delivery enable next-gen content delivery powered by a proven and robust CMS to every touchpoint.

If you would like to learn more about how Optimizely can deliver the business outcomes you are looking for, don't hesitate to get in touch.