The Lifecycle of a GraphQL Query With CrafterCMS

GraphQL has grown rapidly among software development teams and many CMS solutions have moved towards native support of the technology. This is in part because GraphQL streamlines the process of delivering omnichannel digital experiences.

Using GraphQL, developers can quickly develop frontend applications that integrate with CMS systems without learning complicated APIs, database, backend systems, or any other technical knowledge that headless CMSs with only native REST support require.

But just how simple is using GraphQL for retrieving content? Let's take a closer look at how Crafter implements GraphQL and what happens with a content query from start to finish.

How CrafterCMS Adds to the GraphQL Lifecycle

The typical GraphQL server requires backend developers to define one or more schemas, write resolvers, and many other tasks before the API can be used by front-end teams. The schema is a crucial element that enabled GraphQL to be both transport layer and database agnostic, but the schema would still need to reflect any changes to the data structure on the backend. And developers would need to write resolvers for each data type so the runtime engine knows how the actual execution of a query should work on the backend. Optimizing both of these aspects of the GraphQL server is crucial to a high-performance API.

With CrafterCMS, the GraphQL schema is automatically generated for each of your websites based on the content types you define in Crafter Studio. When content authors change these content types, the schema is rebuilt and resolvers are updated to reflect this. If necessary, however, the GraphQL schema can be rebuilt or customized manually.

GraphQL From Start to Finish

There’s no question GraphQL has significant benefits for development teams that require a fast time to market for new applications. GraphQL standardizes APIs, hides the backend implementation details from frontend developers, and improves performance over REST APIs, among other advantages.

We’ve covered these benefits in-depth with Why GraphQL: From RESTful to the Future. With these factors in mind, let’s see just how streamlined the process is with a simple content query.

1. Frontend client POSTs the query to Crafter

The first step in retrieving content using GraphQL is to send a POST request to the GraphQL endpoint with a JSON body containing the query. A simple GraphQL query, for example, would look like this:

# root query
{
 # query for content-type '/page/article'
 page_article {
   total # total number of items found
   items { # list of items found
     # content-type fields that will be returned
     # (names are based on the content-type configuration)
     title
     author
     date_dt
   }
 }
}

This query would retrieve the title, author, and date of all the articles found within the CrafterCMS content repository.

The GraphiQL client within Crafter Studio makes it straightforward to explore and test queries in real-time using an intuitive interface. Developers can quickly search for queries, content types, fields, and more within the tool. This streamlines the development workflow when using GraphQL.

2. The query is parsed and validated by GraphQL

Once the server receives the query, it parses the JSON and transforms it into AST — an abstract syntax tree — that makes it easy to detect syntax errors. If the server does find any syntax errors, it gives an immediate response to the client. Requests can be syntactically correct but still run into issues during execution. That’s why the next stage is validation.

The GraphQL server validates the query against the schema that CrafterCMS automatically maintains. This ensures the query will be possible to execute during the next step without any additional work from the developer. Another key advantage of this validation is that there are reduced risks of SQL injection and other security vulnerabilities. Most REST APIs require additional code to validate requests properly, so GraphQL can greatly reduce developer workloads at this stage.

3. GraphQL executed the query

At this point, the query is executed by GraphQL on the backend. That means the requested content is retrieved from wherever it is stored step by step as the resolvers execute each field within the query. In a sense, GraphQL aggregates the data from multiple data sources, so that frontend end developers don’t have to write the code to do this manually.

This step is essential for GraphQL to achieve significantly improved performance. That’s because the CrafterCMS backend pulls the data as efficiently as possible behind the scenes instead of frontend applications making multiple API requests over the internet to get the necessary content.

4. The client receives the content

After the query is executed by GraphQL, the HTTP response is delivered to the frontend client. The shape of GraphQL responses closely matches the original query, making it straightforward to map to and from API requests on the frontend. Developers get exactly what they need, which is useful for new applications using component-based frameworks and also legacy software that requires highly specific responses back.

Along with simplicity, the resulting response is highly efficient. The JSON in the response body will contain only the information requested in the initial GraphQL query, so there’s less over fetching of data and reduced bandwidth usage. That means greater performance than REST APIs much of the time, and less risk of data leakage as well.

Streamlined GraphQL Support With CrafterCMS

In the end, the frontend developer makes an API request using a standardized querying language — maybe even generated by the GraphiQL tool — to a single API endpoint, and the GraphQL runtime engine and CrafterCMS do all the backend work of parsing, validating, and aggregating the data automatically.

With CrafterCMS, GraphQL really is that simple. Frontend developers get all the benefits of the technology without putting more work on the backend development team. Crafter is ready for queries out of the box, and updates automatically to reflect content type changes. GraphQL enables companies to adapt quickly and launch new content-driven apps quickly and efficiently. There’s less API maintenance, no need to document API changes, and many other tasks that slow development teams down are eliminated. GraphQL, therefore, is ideal for high-performance content delivery.

Learn more about the technical aspects of GraphQL with our take on Is GraphQL the Next API Standard for CMS?