Is GraphQL the Next API Standard for CMS?

Is GraphQL the Next API Standard for CMS?

Back in the 90s, when support for SQL matured, the world was forever changed for the better. SQL standards were created to make relational database queries more portable, ease training, and grow the community and tooling, and they achieved all of this. To this end, the content management community has long searched for a standard API for content repositories and other related concerns. Over the decades we’ve seen many attempts to create a standard that vendors and consumers could rally around including WebDAV, iECM, JCR, and CMIS just to name a few. While some of these have had more success than others, in general, all have suffered from relatively low adoption rates. Why? It’s fair to say that content management is a broad and non-trivial space. 

Just defining an API and gaining consensus is difficult enough, to say nothing of choosing implementation technologies for bindings (SOAP, ATOM, REST, etc.) But the difficulty is not the only issue. The other issue is that the standards have always been somewhat clunky and difficult to work with. This is likely a result of the committee-driven design process which is typically made up of vendors who by necessity bring their vendor-specific baggage and agendas to the process. More importantly, there’s no real-world litmus test for these standards until much later when the implementations materialize. The mediocre success of CMS standards is no surprise. We need an API standard for interacting with our CMS platforms that can go beyond the technical and political challenges faced by previous API(s) to reach a high level of adoption across the entire development community.

Enter GraphQL. GraphQL is a data query and manipulation language with a pluggable runtime for APIs created in 2012 by Facebook to solve large-scale, interrelated data access concerns at massive scale. While committees and standards have a lot of value, GraphQL’s genesis is an example of an alternative design process that began with a practical, specific need and then later grew into a more general solution with a committee to steer its future. To that end, in 2015, Facebook put GraphQL in the open source domain. Since that time, GraphQL has enjoyed tremendous growth in popularity, becoming a de'jour standard in the development community with bindings for well over 15 languages and pluggability with many backends. While GraphQL was never designed to be an API standard for CMS platforms, it may be one of the best things to happen for APIs for content management. Let’s take a look at why.

A Brief Overview of GraphQL

There are many articles on what GraphQL is and how it works. We don’t need to recreate those here but for completeness let’s cover some basics. Feel free to skip this section if you are already familiar with GraphQL’s purpose and basic design.

GraphQL is a Web Services Architecture

GraphQL is a general data query and manipulation web services architecture that provides an alternative to REST and other traditional web service frameworks. REST is a high-level standard that describes the norms of communicating with services over HTTP. That is to say, REST is a protocol definition for the proper handling and application of state, headers, parameters, response codes and so on. REST and similar web service standards don’t dictate anything specific about the contents of the request or the nature of the response content. GraphQL is different in this respect. 


GraphQL defines a standard language for querying and interacting with data. Unlike REST and other similar API standards which are ad-hoc in nature, GraphQL servers require specific request and response syntax along with schemas on the server that ultimately enable them to be interrogated and discoverable to clients. By its nature, GraphQL dictates the shape, depth, and pagination of the response, allowing the client to right-size the request and granularity of the communication. These characteristics have several advantages over a REST-only approach when API complexity begins to scale.

GraphQL is a Query Language and an Execution Runtime

Very simply put: GraphQL is a schema-driven query language designed to sit on top of any kind of backend. Like SQL, consumers request data from a GraphQL server by defining a query that describes both the structure or shape of the response they want along with filters or predicates that should be used to constrain the results in the response. That’s powerful. Unlike a traditional REST API that provides no standard of control over the content and format of a response, GraphQL lets the consumer define what they need. Because of this, development is much faster and API calls are much more efficient because they are consumer specific. Moreover, to support all of this capability, GraphQL provides an execution runtime that makes adding GraphQL support to a data store much easier. Rather than implementing the entire API and query specification, you simply need to provide plugins to the runtime that enable the system to perform data access and manipulation operations for your specific backend technology.

GraphQL is a Data Aggregation Framework

Because GraphQL is schema-based and is discoverable, it’s possible to create a “Graph of Graphs” by layering one GraphQL server on top of other GraphQL servers. This allows a consumer to use a single API endpoint to access multiple data sources and stitch together the responses. One of the challenges with traditional REST-based implementations is fine-grained, chatty communications. Of course, REST itself does not dictate the “chunky-ness” of APIs but the tendency during API creation is to start with simple, atomic data access and then evolve to more composite based APIs later. What API consumers need is difficult to anticipate and it can be difficult to prioritize on-going development once an API is published. GraphQL natively provides a full spectrum of granularity and support for composite services right out of the gate with no extra work required. Consumers define use-case specific requests for data with the perfect level of granularity on day one.

3 Reasons Why GraphQL May Be the Best API for CMS

Let's look at some of the specific advantages that GraphQL offers as an API on top of CMS and digital experience platforms.

Reason #1: GraphQL is Widely Adopted and Easy to Learn

Our first reason goes right to the heart of one of the main issues with traditional CMS API standards: adoption. GraphQL has massive adoption levels with developers of all kinds. In the past, CMS APIs have had to try and rally adoption. GraphQL is a general technology and already has adoption en mass across a diverse and active development community. 

Content exists in nearly all of our applications today. Being able to edit and manage that content would provide a tremendous value. Yet, despite the value CMS could offer, priorities combined with high, vendor-specific and language-specific learning curves have warded off the larger development community. GraphQL’s massive adoption offers an opportunity to change all of that and bring CMS to a much wider range of use cases and developer communities.

What is driving GraphQL adoptions?

GraphQL is Real Open Source

Developers are smart and cautious when it comes to the adoption of standards and open source. They can smell an agenda-driven standard or a fake open source project a mile away. GraphQL has easily crossed that hurdle. Today GraphQL uses a standard open source license (MIT) and the Linux Foundation in cooperation with the GraphQL Foundation, who (rather than Facebook) owns the trademarks and manages the development and ecosystem of GraphQL. When it comes to adoption from developers, real open source matters and GraphQL is real open source software.

GraphQL Success Stories are Piling Up

Facebook started GraphQL based on its own real-world, complex needs around social data. Solving these problems was trial by fire at Facebook’s scale. When the GraphQL first became open source, its achievements at Facebook earned a lot of interest in its general applicability from the development community. Several years since it’s open source debut, large-scale, high-profile GraphQL success stories continue to accumulate.

API Standardization is a Top Objective for the CIO

Most organizations have either mandated the move or have already moved to API-first strategies. As organizations move through the API maturity model, standardization becomes key to the realization of the full benefits of the approach. Standardization of interface, versioning, security, metering, and monitoring are just a few examples of the overarching concerns that need to be addressed. GraphQL as an API and API gateway provide a solid starting point, if not a turnkey solution for addressing many of these concerns.

GraphQL is Accessible to Many Programmers

GraphQL has language bindings for over 15 languages including JavaScript, Java, Perl, Python, Ruby, C#, Scala, Go, Clojure and many others. The basics of using GraphQL are simple and easy for a developer to learn. Once a developer understands the basics, any data source fronted by GraphQL becomes something they can easily build on across a wide range of technologies.  

Reason #2: GraphQL is Ideal In a Multi-Channel World

Today’s digital experiences are multi-channel. Companies use many touch-points from websites and native mobile apps to email, chat-bots, digital assistants and other channels to interact with their customers. GraphQL maps directly to the multi-channel world we find ourselves in. Here’s how.

GraphQL Maps Directly to Headless CMS Architecture

For the most part, every channel has its own lifecycle and are often built with specialized frameworks and technology. While there is a lot of variation in implementation, much of the messaging and other content remains the same between channels. Headless and hybrid headless CMS platforms which serve content via presentation-less web API calls address this concern. GraphQL provides a more general, de’jour standard alternative to vendor-specific web APIs that’s powerful, flexible and easy to use.

The Flexibility of GraphQL Makes Supporting New Channels Easy

Innovations in technology and evolving customer expectations drive the constant addition and adoption of new channels. Often times first movers in a new channel are big winners. Organizations that are well positioned technologically to launch support for new channels have an advantage over competitors. Anything a CMS can do to provide this advantage is a win. A GraphQL-native CMS helps in several ways.  


First, there is language support. New channels often mean new languages and frameworks. GraphQL lets us leverage the same API across a wide range of technology. Second, because GraphQL is schema-based and declarative its consumers can be specific about the content they want back and the structure or shape they want that content back in. That’s huge. Not all channels need the same content items, fields or granularity. A GraphQL-native CMS can support any channel specific needs with no new development on the server.

Reason #3: Easily Combine Content with Other Data 

Digital experiences always require content but they often require other data as well. Examples include core product data, inventory data, and user data to name a few. This kind of data often lives outside the CMS in other systems. In a traditional world without GraphQL, applications had to call vendor-specific APIs and marry content and data from disparate systems. This is inefficient from both a development and a system communications/data transfer perspective. Because GraphQL is a general API and runtime that sits on top of any datastore it can be used to create a single, uniform API entry point for your enterprise. GraphQL supports a concept called Schema-Stitching which is the ability to layer one GraphQL API upon other GraphQL APIs (Graph of Graphs.) Through this mechanism not only are our digital experiences able to request content efficiently but they are able to marry our content with other relevant data in a single, consistent request that’s specifically tailored for a given need.  

Is GraphQL the Silver Bullet of API(s) for CMS?

Clearly, GraphQL has massive adoption amongst developers and technical advantages as an API for CMS platforms that make it attractive compared to traditional CMS API standards and vendor-specific APIs -- but is it a silver bullet? No. Let’s look at some things to consider along these lines:

Not All GraphQL Enabled CMS Platforms are Created Equal

GraphQL sits on top of underlying data and content stores and are thus subject to their performance profile, security, and other architectural and capability limitations. GraphQL’s ability to deliver content via API in a way that is tailored for consumer’s use-case specific needs is outstanding but if the interface can’t achieve adequate performance due to latency and throughput issues caused by the underlying implementation and architecture or if the implementation can’t be scaled out on-demand elastically to handle large request volumes the advantages of the interface are lost. Another implementation-specific topic is schema management. How the CMS handles GraphQL schema updates as the CMS’s content type definitions mutate can differ from one implementation to the other. Whatever approach is taken needs to be simple, transparent and scalable. These concerns are non-trivial and it’s important to understand that not all GraphQL implementations are created equally.

Comprehensive CMS-Oriented API Coverage

For the most part, CMS standards have focused on read and write at the repository layer as well as key concepts content management specific concepts such as collaboration based locking and versioning of content. GraphQL provides support for read and write operations but these other CMS specific concepts and concerns don’t specifically fit or map as neatly. That is not to say that GraphQL can’t do the job to support the creation and access to versions of a content item, as an example, but the API may not feel as natural as an API specifically designed to address that domain-specific concerns.  

Conclusion

GraphQL is a general data query and data manipulation API and runtime with a high degree of adoption amongst developers. GraphQL offers significant advantages over traditional web services architecture and APIs for specific content and digital experience oriented use cases.

That said, as a more generalized data access technology, GraphQL may be somewhat less useful on the management side of the CMS equation, where more specific, targeted API(s) can better map to concepts and drive better semantics and performance because they relate directly to the problem domain. 

Where GraphQL seems to excel the most is on the delivery side of CMS. GraphQL is a near perfect fit for today’s multi-channel content delivery demands. It’s modern, powerful, flexible and lightweight as API technology and it enables consumers to get exactly the data volume and granularity their use case requires with no additional coding on the data’s source system. Because these benefits, GraphQL already has massive adoption throughout the development community. These are characteristics no CMS API standard to date can claim making GraphQL today’s most likely candidate as a standard for headless content delivery.

Share This Article :

Russ Danner

Russ Danner

Russ Danner is VP Products at Crafter Software and is responsible for product management, product development and support, and client and partner success. Russ brings over 20 years of software architecture, design, and implementation experience. Prior to Crafter Software, Russ was Web Experience Management Practice Director at Rivet Logic and project lead for the open source Crafter CMS project. Russ has also been active in the Alfresco community since 2005 as a community leader, contributor, trainer, speaker and user group organizer.