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 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 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.
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.
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.
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.
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 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.
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.
- 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.
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.
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.
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.
- Avoiding Direct Headless CMS Service Access – Deliverystack.net
- Whether to Use Vendor SDKs to Access Vendor Services – Deliverystack.net
- Three Major Phases for Data Access in Headless Content Management Solutions – Deliverystack.net
- Advantages of Event Systems with Headless Content Management Systems – Deliverystack.net
- Differences between Decoupled CMS and SaaS Headless CMS – Deliverystack.net
- Headless CMS with Webhook and API Brokers – Deliverystack.net
- Integrating Event Systems with Headless CMS – Deliverystack.net
- Customizing and Extending SaaS Headless CMS User Interfaces – Deliverystack.net
- Centralizing [Headless] [CMS] Data Access – Deliverystack.net
- Working with [Headless] [CMS] Vendor [.NET [Core]] SDKs – Deliverystack.net
- You’re All Doing It All Wrong – Deliverystack.net
- Why Isn’t This In the .NET SDK? – Deliverystack.net
- The (Best) [CMS] API Has No Methods – Deliverystack.net
- What and How to Index for Search with Headless CMS – Deliverystack.net