With the release of dotCMS 5.1, our enterprise Java CMS now natively supports GraphQL. In this article, I’ll walk you through the basics of GraphQL as an API and query language, how it differs from REST, and how dotCMS and GraphQL come together to streamline headless content management.
See dotCMS and GraphQL in Action →
What is GraphQL?
GraphQL is an open-source data query language for APIs. It enables users to specify exactly what data they would like to retrieve from the server. Developed by Facebook in 2012, GraphQL became open-sourced in 2015. It is used internally for mobile applications, and it is widely seen as an alternative to the REST (Representational State Transfer) architecture.
More precisely, GraphQL performs three key tasks: allows the clients to pick exactly what they want, uses a type system to describe data, and obtain data from multiple server resources in a single call.
The latter process was difficult to do with REST since the backend defines the data available for each resource on every URL, while the frontend has to request for all the data in a resource. This is known as over-fetching. Having a query language such as GraphQL on the client-side and server-side allows the client to pick the data they want by making a single request to the server which reduces the chances of over fetching or under-fetching data.
GraphQL vs REST: What’s the Difference?
When it comes to network requests between the client and the server, REST is among the most popular options to connect both worlds. It is widely used, and it enables developers to action stateless calls between applications and services and structured access to resources. REST utilizes HTTP request to GET, POST, PUT, and DELETE data.
Although REST has been the go-to option for designing web APIs, it seems to be too inflexible to keep up with the ever-changing requirements of the clients that access them. For instance, when retrieving content with REST API, a lot of the times you get back more than you bargained for. With each request, you get a ton of “unwanted” metadata when you’re really just after the title, image, and the body text.
GraphQL was developed to fulfill the need for more flexibility and efficiency—to ultimately excel where REST does not GraphQL solves the inefficiencies that web developers encounter especially in data fetching. In this case, you simply send a single GraphQL query to the server with all the data requirements. The server then returns with JSON points with all the requirements fulfilled. A single GraphQL operation supports a query (read), mutation (write), and the subscription to changes to data (continuous read) based on the schema. Once this operation information reaches the backend, it is interpreted against the whole GraphQL schema and fixed with the frontend data application.
In line with the needs of dotCMS’s enterprise clients, our open source Java CMS now natively supports GraphQL, empowering developers to query every content type as a collection, including HTML, content types, categories, and personas. Specifically, our support of GraphQL enables you to perform a query across the entire content repository, similar to Elasticsearch, to generate a schema. No Java coding is required, and your dotCMS instance automatically returns the results based on your specified requirements.
The Benefits of GraphQL Over REST
Let’s now summarize the benefits of GraphQL, and to illustrate how it improves upon REST as an API and query language.
GraphQL is “Self-documenting”
GraphQL reduces the need for documentation in two ways. Firstly, because it has been designed to be easily understood by engineers, even without prior knowledge of GraphQL. Lee Byron, one of the developers of GraphQL, made reference to this in a presentation delivered at GraphQL Summit 2016:
“Imagine that most of the engineers who are going to be using your API might not find it so easy to go and find out how that field maps to some underlying system. It’s really important not just to have names that are good but to have names that are self-documenting. Naming things that adhere closely to what those things actually do is really important to make this experience actually work,” Byron said.
Secondly, GraphQL boasts introspection capabilities, allowing users to query the system’s endpoints and objects to quickly discover their functionality.
Say Goodbye to Overfetching and Underfetching Data
As mentioned, REST often gives you more than you bargained for, which makes querying slower and more difficult to manage. But with GraphQL, you can specify exactly what you want to query, including the title, image, or body. Ideally, content, personas, or HTML pages can be mapped into base types in the GraphQL interface meaning that you can query all the files regardless of their types as a collection.
Once the content types are modified, GraphQL rebuilds the schema and allows users to query upon things they want.
So, with GraphQL, you can pick the fields you want to query, ensuring the request will always be the smallest possible. Plus, GraphQL allows you to query multiple entities in one request, making it more efficient than REST.
dotCMS and GraphQL: How it All Works
So, how does dotCMS's new GraphQL support come together? This section will explain how to connect dotCMS 5.1 with a GraphQL endpoint.
To start, request an access token from the local dotCMS which includes typing your username and password. Remember to set the token’s expiry date to a thousand days.
Next, create it as a New Request.
Our auth is going to be the Bearer Token which represents the access token. Then save that.
Then, you need to put in your endpoint. In this case, the endpoint for GraphQL is API v1, then proceed to do your query.
In doing so, what will happen is that it will fetch the GraphQL schema. Since the GraphQL is self-documenting, the tool will start doing auto-complete.
From here, the schema will allow you to select what you want from the fields. For instance, the title, byline, lead, and so on. For this example, we want to query news articles that have a particular type of content. Once you send this query, you should see something like this:
The interesting part about GraphQL is that you can proceed to query other objects within the repository and you get a set of values for anything you need. For instance, you can get the host folder path (1) (access the folder path, hostname), image (2) (get the path, name, and size), and so on. When applying these additional queries, you should see the following:
For categories, you can retrieve more sections such as the inode, name, velocity variable in any given category as shown below:
Tags section will return a complete format of how the piece of content has been tagged to different fields.
Also, you can do a broader query commonly known as a “join write.” Let’s say you want to query content types such as news and content writer. For both of them, you want to identify the title and the identifier. For the news article (1), you want to pull the URL and byline, and for the content writer (2), you want to see the first and last name. Here is what you should see once you send the query:
Ideally, you can query multiple types of content within a single query, and for each of them pull back the fields and properties you require.
What’s Next with dotCMS’s GraphQL Support?
In a nutshell, headless content management is evolving to support IoT devices, single page applications, progressive web apps, and other touch points. GraphQL is one technology that’s fueling this evolution, especially when it comes to JavaScript development. With advantages such as self-documenting, declarative data fetching, and no over-fetching of data, it’s clear that GraphQL is a game changer in the headless CMS space, which is why we’ve worked hard to bring GraphQL support to our enterprise customers.
At the moment, dotCMS's GraphQL enables you to query the content repository. In future releases, we’ll be exploring ways in which you can use dotCMS’s GraphQL support to perform ‘mutations’ which will allow you to modify content with GraphQL query requests as well as update and delete content. Without a doubt, we see great potential in GraphQL, and we can’t wait to see how our enterprise customers, from TELUS to The Lebron James Foundation, will leverage it tandem with our Content as a Service features.