Coupling in [Headless] CMS

This blog post discusses forms of coupling between content management and content delivery systems in the context of headless CMS. Vendors use the term decoupled rather loosely and inconsistently, generally to indicate that content delivery does not depend on content management, but without describing exactly how. As I tried to understand what decoupled means, a more complex picture emerged, with several possible forms of coupling possible at different phases in the solution lifecycle. The systems are not entirely decoupled: whatever element(s) of content delivery (static or dynamic HTML generation, client-side JavaScript, search engine indexing, data export and synchronization processes, or otherwise) must retrieve data from and therefore have knowledge of and access to the content management system. It is not possible to use a CMS without some form of coupling, and the more of the CMS a solution uses, the tighter that coupling becomes. In the most general sense, decoupling refers to loosening coupling and altering its placement in the solution lifecycle. If you have perspectives on coupling in headless CMS or service-oriented architectures in general, please comment on this blog post.

Coupling and Decoupling

One primary objective of modern enterprise application architecture is to decouple systems, which generally means reducing logical and runtime dependencies between applications, generally meaning fewer direct interfaces and dependencies. In the case of headless content management, the decoupled systems are the content management system where CMS users maintain data and the content delivery solution that makes that content available to public visitors. The content delivery solution implemented by the customer can retrieve data from content delivery services in the CMS, which represents a form of coupling between content management and content delivery systems.

Decoupling refers to the separation of content delivery systems, such as websites, from content management systems that contain data that drives the solution. Decoupling involves using software services to exchange JSON over HTTPS rather than accessing databases or invoking platform native technologies directly. Decoupling has numerous advantages including insulation, administration, scalability, agility, reduced vendor lock-in, and otherwise.

Forms of Coupling

The topics in this section describe the potential forms of coupling summarized here.

Runtime Coupling: Any content delivery runtime dependency on content management including content delivery services.
API Coupling: Any use of CMS APIs.
SDK Coupling: Any use of CMS SDKs.
Installation Coupling: Building the content delivery solution on a software installation from a CMS vendor.
Data Format Coupling: Any use of vendor-specific data formats, URLs, parameters, or otherwise.
CMS UI Coupling: Using vendor logic and component UI libraries
Webhook Coupling: Any use of webhooks.

Runtime Coupling

Runtime coupling occurs when the content delivery solution depends on the content management solution, including content delivery services provided by the content management solution. Runtime coupling occurs when a dynamic HTML generation facility such as an application server, edge function client application, or anything else that is not part of the site build process invokes a content delivery API, including GraphQL.

API Coupling

API coupling refers to anything that invokes any CMS API. Invoking an API requires significant knowledge about the CMS, including authentication information, the base URL for services, the path to each individual service, query string and HTTP headers, JSON payload, response format, and otherwise.

SDK Coupling

Software Development Kit (SDKs) are programming libraries for specific platform technology such as JavaScript or .NET. With headless CMS, SDKs primarily wrap and abstract HTTPS service APIs.

Using an SDK from a vendor represents has similar concerns to invoking APIs directly but may represent tighter form of coupling, as the solution may depend on the vendor to provide coverage for all APIs and parameters and to release updates to the SDK.

Installation Coupling

Customer solutions built on dynamic content delivery engines provided by a CMS vendor depend on an installation of that CMS software. In addition to this form of runtime coupling, installing and maintaining CMS instances, especially across multiple projects and environments, is a relatively expensive undertaking.

This concern is generally irrelevant to SaaS headless CMS, where vendors provision and maintain hosted environments for their customers. Rather than building customer solutions on top of the content delivery software, headless customers build their content delivery solutions next to the CMS, consuming its content delivery services.

Data Format Coupling

Data format coupling refers to the use of vendor-specific URLs, query string parameters, HTTP headers, cookies, URLs, JSON formats, and any other details such as those used by webhooks and HTTPS APIs including GraphQL. Each system should have minimal knowledge of these technical specifics about other systems.

Implement abstraction and normalization layers between applications, such as API and webhook brokers or an enterprise message bus.

CMS UI Coupling

Many solutions involve custom extensions to the content management user interface. For example, almost every CMS allows custom user interfaces in the list field types available when defining data structures.

The level of UI coupling cany vary. At its simplest, a customization can reference a JavaScript library and likely a stylesheet from the CMS vendor, and a custom field can store a value to the entry. Using a user interface component framework from a vendor represents a tighter level of UI coupling.

If the customer hosts CMS UI customizations rather than the vendor, then those features of the CMS UI have a runtime dependency (coupling) on that hosting.

Webhook Coupling

You can configure webhooks to signal other systems when events occur in the CMS. Webhooks are HTTP requests from the CMS to target systems, where the request includes a payload containing information about the event that raised the webhook.

Webhooks present both data format coupling and runtime coupling. To configure a webhook, the CMS must know the URL of the external system, and that webhook listener must understand the data format of the webhook payload. Optimally, an intermediary such as a broker or message bus insulates systems that depend on webhooks.

Toolset Coupling

Toolset coupling refers to vendors that suggest or even require the use of specific technologies, such as Node.js or .NET. The more vendor-specific technologies a solution employs, the more tightly coupled the solution is to those vendors.

Coupling Phases

There are at least five phases during which coupling between content management and content delivery systems can occur. If possible, couple (invoke CMS APIs) at the minimal number of phases, generally in this order of preference.

During the solution build process, such as while generating static HTML from data in the CMS.
On the client at runtime, such as calling CMS content delivery services from JavaScript to retrieve and render additional content.
From custom services used by client applications.
During server-side runtime HTML generation, such as when using an application server or edge functionality to service or modify HTTP requests dynamically.

The fifth is during content management, such as CMS user interface customizations.

Decoupling Strategies

There are several strategies to loosen various forms of coupling between systems.

Centralize: Implement a code layer that abstracts all access to vendor systems.
Minimize: Avoid excessive reliance on the CMS, for example for search.
Export: Export data from the CMS to files or other intermediary systems.
Static: Access content delivery APIs during a static site build process rather than at runtime.
Brokerage: Implement a brokerage architecture to insulate systems.
Message Bus: Use an enterprise message bus to insulate systems.

Probably the most significant of these is static site generation, which is prevalent for Jamstack solutions. Runtime coupling indicates a content delivery system that cannot function without the content management system, including its content delivery services. To eliminate runtime coupling, the content delivery solution must have no runtime dependency on the content management system and must make no use of its APIs or data formats at any phase beyond build. Solutions can generate static HTML from content in the CMS or export and normalize content from the CMS into another system such as JSON files or a search index. The solution build and possibly update processes perform the coupling between content management and content delivery, which minimizes and centralizes the coupling surface.

A completely static solution can achieve dynamic behavior with JavaScript, but not include content that was published after the most recent site build or update process completed. To provide for dynamic functionality based on data updated in the CMS, JavaScript served as part of the static solution can invoke content delivery services in the CMS, which re-introduces runtime coupling.

Every use of a vendor-specific data format, SDK, API, webhook, CMS extension point, or other feature from a vendor represents software coupling between customer and vendor systems, which increases the cost of migrating between vendors.

To reduce vendor lock-in, employ architectural approaches that minimize software coupling. Normalize data to independent formats before use. Index, cache, or otherwise export data to intermediary storage mechanisms. Employ an enterprise message bus to insulate system interactions. Abstract, broker, minimize, and centralize use of vendor features.

The more features the CMS provides, the tighter the software coupling is likely to be. For example, a CMS that supports inline editing, allowing CMS users write access to the content management environment, must invoke CMS APIs, where solutions that do not allow write access can use data exported from the CMS rather than accessing it directly.

Search engines can provide a great intermediary between the content delivery solution and the CMS, moving much of the coupling from the CMS to search, which can have numerous advantages.

Links

I feel like this post is too long (sorry I didn’t go back to edit better), but still incomplete. Here are links to some additional information that could be relevant. Please ask questions or make suggestions in the comments.

3 thoughts on “Coupling in [Headless] CMS”

Pingback: What Does It Mean for a CMS to Be Headless? – Deliverystack.net
Pingback: Contentstack JSON Data Formats: Modular Blocks – Deliverystack.net
Pingback: .NET 6: Normalize JSON Before Deserialization with the Contentstack SaaS Headless CMS – Deliverystack.net