What is GraphQL and why it matters for headless CMS

Software developers collaborating at a table

First developed by Facebook in 2012, headless CMS architecture is the solution of choice for many a CMS these days. GraphQL is the programming language that enables flexible connection with programming APIs that support headless CMS integrations like the one offered through Brightspot.

Headless CMS
Download this e-book for a technical buyer’s guide to headless CMS architecture and the GraphQL query language.

When it comes to content management systems, headless CMS architecture is a rising star these days. The on the topic looks like one side of a mountain, with the base planted in 2012 when Facebook first developed “headless” architecture internally. The hype over headless has grown, at least in part, because the CMS 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 CMS 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.

Everything you need to know about GraphQL

Here are some common questions about GraphQL, and the various pros and cons to the different CMS integration approaches.

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.

    Advantages of GraphQL architecture for an API-based CMS

    What are the benefits of GraphQL?

    A GraphQL CMS 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 CMS 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, our API based CMS and DAM has developer tools for writing and sending GraphQL queries, and the self-describing type system allows for 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 architecture 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.

    GraphQL and headless CMS considerations

    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 GraphQL CMS offers a solution, but developers will need to judge for themselves whether those solutions make headless a good match for their needs.

    Problem 1: Performance/caching
    • Because GraphQL CMS 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’s GraphQL headless CMS 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.
    Problem 2: 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 from native apps using a service from . 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 CMS API, then Brightspot will return data specific to the content the editor is modifying.
    Problem 3: 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.
    Problem 4: 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 CMS 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 CMS architecture: Which one to choose?

    Which of these CMS 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 about headless CMS in this article.

    Still have questions? Check out our webinars page, where we dive into even more detail on the ins and outs of a headless CMS, or contact us to schedule a demo.


    More headless CMS resources

    Explore the shift from headless to hybrid CMS. Learn why flexibility is key in modern CMS architecture, featuring insights from CEO Raleigh McClayton.
    Previously hosted on Drupal and two other platforms, Australia's multilingual public-service broadcaster, Special Broadcasting Service, is now able to deliver to its front-end head via Brightspot headless CMS.
    In our work with clients and in webinars, we field lots of questions about headless and decoupled CMS architecture. Here are answers to some of the most common.
    Is a headless CMS the superior content management system solution? The answer, of course, depends, but ignore the hype and get the information you need to make the most informed decision to suit your exact business needs.

    Let us give you a demo

    Hear how Brightspot can turn your digital strategy goals into a reality and see how the lives of your content creators and developers will be changed using our platform.

    Request Demo