Avoiding Direct Headless CMS Service Access

TThis blog post describes techniques to avoid tighter coupling introduced by calling service-oriented application APIs directly, such as those exposed by headless content management systems (CMS). If you have suggestions for further insulating systems, please comment on this blog post.

Service-oriented architectures including headless CMS intend to loosen coupling between systems. Using HTTPS APIs rather than platform native APIs allows any systems to interoperate, regardless of their underlying technologies, and with minimal knowledge of other systems. Without service APIs, tight coupling leads to hard dependencies on vendor products. Using HTTPS APIs leads to softer dependencies but does not eliminate coupling between systems.

Service-oriented systems may be separated by the Internet, but they must be aware of domain names, authentication credentials, URL paths, query string parameters, environment specifiers, and JSON formats used by the other, even if much of this can be stored in configuration rather than code. In addition to depending on vendor-specific URLs and HTTP headers, when systems invoke remote HTTPS APIs, they exchange data in vendor-specific JSON structures that are less likely to be managed as configuration. The greater the number of APIs that a solution invokes directly, and the greater use it makes of its structures, the tighter that solution is coupled to the vendor.

You can use various techniques to loosen coupling between systems and vendors. With each approach, restructure any JSON to avoid vendor-specific formats and exclude irrelevant data from the vendor before storing or otherwise passing the data downstream. Clients should have no knowledge of upstream resources such as the content management system and its proprietary data structures.

In all cases, consider performance and scalability, which often involves caching. Headless CMS vendors leverage content delivery networks; custom services should implement similar functionality.

In some cases, it may be appropriate to combine approaches.

Centralize Access

You can implement a programming layer that centralizes access to resources. Headless CMS vendors provide SDKs that implement such a programming layer.

You may want to branch or duplicate code from the vendor’s SDK into your own library so that your solutions do not have a direct dependency on the vendor, allowing you greater control. Solutions that use fewer APIs require less vendor-specific knowledge and are easier to migrate from one vendor to another. To prevent developers from accessing arbitrary APIs, you may want to limit what is available in your version of the library.

Rather than using a vendor SDK, you may want to implement a programming layer that completely abstracts only those APIs that you use, possibly using a domain model rather than vendor-specific APIs and data formats.

Export and Synchronize

At the cost of maintaining synchronization, exporting data to a file system, database, or other repository completely avoids a runtime dependency on the source system including its APIs and data formats. The export and synchronization processes are the only pieces of code that work with vendor APIs and JSON structures.

If you choose to export, investigate the availability of APIs intended for synchronization from your vendor.


Define indexing logic to store raw normalized data from the source systems such as CMS. Implement client applications to retrieve data directly from search rather than from the source systems.

Because search can be a performance-critical function, clients may call search APIs directly rather than using additional layers of abstraction. Excessive complexity in search APIs could complicate migrations from one search vendor to another.

Event System

Event systems manage the flow of information between systems. You can implement webhook listeners that publish data to the event system, such as to process events from the CMS. You can implement subscribers that access CMS APIs when needed.

API Broker

An API broker can function as an intermediary between systems, reformatting HTTP requests from clients for upstream systems and reformatting their responses to the client. Your solutions are aware of the services that your broker provides, not the services provided by the individual vendors that the broker abstracts. This approach allows centralization of access credentials for multiple vendors that would otherwise require distribution, such as headless content management tokens, as well as a consistent security layer for all clients of the broker.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: