GraphQL vs REST: What's Best for Web Content Management

Traditionally speaking, content management systems (CMS) were server-based.

These systems received queries from clients, generated HTML responses, and sent those responses back to the clients and displayed the content in web browsers. The development of headless CMS systems, such as our own open source dotCMS, has lightened the load on servers by using clients to generate the content, while still employing servers to hold the relevant data and process queries from clients.

The development of a number of tools has helped developers in their efforts to generate content on the client side. Each of these tools has its uses, as well as its limitations, depending on the infrastructure in which they are deployed.

Here, I’ll give an overview of the difference between GraphQL and REST and what they mean for your content management system. I’ll be using dotCMS as an example web content management system; however, these ideas can be applied to most CMSs on the market.

What Is GraphQL?

As the name would suggest, GraphQL is a query language. Much in the same way that SQL (structured query language) determines the syntax of how a query requests specific data from a database, GraphQL determines the syntax of how a query requests data to present content via an API. GraphQL enables the user to make a single call to retrieve the specified data through the API, which makes it easier to collect data from various sources.

Limitations of GraphQL

While many top-flight sites, including Facebook, have embraced GraphQL, the language does have its limitations. Since GraphQL queries always return an HTTP status code of 200, regardless of if the query was successful or not, this issue can make error tracking problematic. GraphQL also lacks built-in caching support, so developers must provide their own caching support, or use globally unique identifiers (GUIDs) to provide the same functionality.

With dotCMS on the other hand, enterprise brands can benefit from built-in caching out-of-the-box. That’s because dotCMS maintains multiple different cache regions to improve performance by enabling efficient handling of different types of data and content.

How dotCMS Supports GraphQL

dotCMS offers native support for GraphQL with dotCMS 5.1. This built-in support exposes the dotCMS content repository as GraphQL, as well as providing an API that lets developers run queries and return specific properties of the desired content while shaping the API response when the call is made. For instance, dotCMS allows developers to specify which data points they want to retrieve through GraphQL queries without overfetching and retrieving unnecessary data. GraphQL also leads to better performance by reducing additional API calls from underfetching.

For reference, let's see how dotCMS supports GraphQL.

What Is RESTful API?

REST (REpresentational State Transfer) is a set of guidelines — or an architectural style — which developers may follow when building an API. These guidelines are usually implemented in combination with existing HTTP methodologies to simplify the communication between a server and client into a series of smaller modules. This modular design gives developers a higher degree of flexibility because data is not tied to a particular method or resource. Since RESTful API calls are stateless, and requests to the API are therefore standalone, this system has shown to be highly useful in developing cloud-based applications.

In the context of a headless CMS, REST APIs help to access the content in the repository and return XML or JSON to expose the content to the visitor requesting it. It is one of the most common APIs used by headless content management systems, as well as other business applications.

Recommended: Headless CMS vs Hybrid CMS: How dotCMS Goes Beyond Headless

Limitations of RESTful APIs

A significant issue with RESTful APIs is that they can sometimes retrieve more data from a request than the client needs. While GraphQL allows for queries to retrieve specific content, RESTful API calls do not provide that built-in functionality. This lack of specificity in calls can force developers to sort through unnecessary metadata just to find the essential data (e.g. title tags, body text, images, etc.) they originally requested.

Is GraphQL Superior to RESTful APIs?

GraphQL has many features that make it more preferable to using RESTful API calls. Responses in GraphQL queries only contain the information needed, while RESTful API calls can be overstuffed. Also, a single request in GraphQL is often sufficient to fill the client’s needs, while RESTful API calls may require several calls to various sources. However, GraphQL also has a steep learning curve and requires extra infrastructure, while RESTful API calls often do not require additional client-side libraries.

If you enjoyed this article and want to learn more about GraphQL, check out this collection of tutorials and articles on all things GraphQL.