What GraphQL Is and Why It Matters for Headless CMSs

When it comes to content management systems, headless architecture is a rising star these days. The Google Trends line graph on the topic looks like one side of a mountain, with the base planted in 2012 when Facebook first developed the architecture internally. The hype over headless has grown, at least in part, because the architecture complements front-end frameworks based on JavaScript, the most widely used programming language of the web.

The Google Trends mountain for headless starts a steep upward incline in 2015, the year that the public GraphQL specification was developed, opening up headless architecture to a wider audience. GraphQL has since become an open standard and is an important part of what makes headless such an attractive option for CMS applications.

What Is GraphQL?

GraphQL is a query language for APIs and a runtime for fulfilling those queries with existing data, providing an alternative to the traditional RESTful style of web services. RESTful style tends to have very loose guidelines for how an API should be structured, while GraphQL strictly structures the communication between the client and the server, irrespective of the specific data models used.

GraphQL has a number of features that benefit users:

• Get just what you need. If one app needs two fields, while another needs 10, you don't need multiple API endpoints, and the app that needs only two gets only two.
• Gather many resources in a single request. GraphQL APIs gather all the data your app needs in a single request, unlike REST APIs that require loading from multiple URLs.
• Describe what’s possible with a type system. GraphQL has a self-describing type system that helps clients discover which data types and fields are accessible from the API. If a new field is added to a Brightspot content type, the GraphQL schema will automatically reflect it.
• Move faster with powerful developer tools. Brightspot has developer tools for writing and sending GraphQL queries, and the self-describing type system allows for the inclusion of features like auto-complete.
• Evolve your API without versions. Adding new fields and types to your GraphQL API doesn’t affect existing queries, and tools exist to deprecate and hide aging fields. By using a single, evolving version, GraphQL APIs give apps continuous access to new features and encourage cleaner, easier-to-maintain server code.
• Bring your own data and code. GraphQL is not limited by a specific storage engine, and it allows you to create a uniform API across your entire application. GraphQL engines are available in many languages to help you write GraphQL APIs that leverage your existing data and code. You provide functions for each field in the type system, and GraphQL calls them with optimal concurrency.

Should Every Project Use a Headless Solution?

The short answer is no.

Despite the popularity and front-end freedom of a headless CMS, it isn’t without its drawbacks. It’s not a one-size-fits-all solution; how you approach it and which hurdles you’ll run into depend on factors such as what type of web application you’re building, the dynamics and skill sets on your team, and the use cases and requirements you have to implement.

A headless solution’s lack of a built-in presentation system comes at a cost. The freedom that you enjoy when using these systems means that you are responsible for writing, debugging and maintaining everything that your rendering system requires.

What Are Headless’ Problems, and How Do I Solve Them?

Going completely headless introduces a number of potential problems. In each case, Brightspot offers a solution, but developers will need to judge for themselves whether those solutions make headless a good match for their needs.

Performance/Caching 

• Because GraphQL queries can be very large, they require POST requests to fetch the required data. A CDN isn’t capable of handling these requests. The front-end app can employ its own client-side caching, but that doesn't scale for large websites.
• Brightspot employs a technique called "Automatic Persisted Queries,” which has the client send a generated ID instead of the large query text as the request. Since the data fields that an app requests are generally static, the app can generate a hash at compile time (or even runtime) for all of the queries that it makes. Brightspot registers the hash-to-query mappings so the correct query is made the next time that hash is requested.

Preview 

• In a headless implementation, the rendering of your application is happening external to the CMS, so live preview is not incorporated into the system. How will editors know how their publishing changes in one system affect the presentation of another?
• Brightspot's preview system is extensible. We have custom preview implementations to support preview print templates from InDesign and from native apps using a service from appetize.io. Similarly, you can specify the URL to your app, and Brightspot will Iframe it into the preview pane and pass along a special preview ID. If the client uses that same preview ID when making its call to the GraphQL API, then Brightspot will return data specific to the content the editor is modifying.

Image Sizes

• Brightspot's rich image editing and cropping capabilities rely on knowledge of the image sizes that the front-end application uses. Since the app is separate from the headless CMS, how can it fetch those hand-curated images from the CMS for rendering?
• Brightspot's image sizing system is also extensible. Clients will be able to define their own configuration file of their standard image sizes and register that with Brightspot. Brightspot will read that data and display all of their defined crops in the image editor and return appropriate image URLs from the GraphQL API based on the backing ViewModels.

Security 

• Code running in the client's browser is completely open and visible to the public, and anyone can view the data transferred from APIs. GraphQL developers must be explicit about which fields they are fetching in order to mitigate risk, but a malicious user could still inspect the schema and make their own queries to fetch additional data not used by the app.
• Even in Brightspot’s headless model, our View System still sits in between the raw Database Model and the ViewModel that's returned by the GraphQL API. This allows for the data to be transformed and sanitized on the back end before transferring back to the client. Even if a malicious user queries for data not used by the app, we can ensure that the ViewModel only contains data that is safe for public consumption.

Decoupled vs. Headless: Which One to Choose?

Which of these architecture types you’ll want to choose will depend on your specific use case.

Even though traditional content management systems have many restrictions that may limit users unnecessarily, there may be a particular one that has better UI, integrations, support, documentation, and features than another CMS that is decoupled or headless. A specific, prioritized functionality may make the restrictions worthwhile in your particular case.

More often than not, a decoupled CMS will be a good bet for content-heavy websites, such as a news site, while a headless CMS will work well for single-page applications (SPAs), such as e-commerce or social media sites.

Making the determination about which solution is best suited to your business can feel overwhelming. In our work with clients and in webinars, we field plenty of questions about the various types of CMS architecture. We answered eight of the questions most commonly asked in this article.