This blog post discusses opportunities and issues relevant to storing JSON from a headless content management system (CMS) as files in the content delivery tier of a dynamic website.

Update 15.Dec.2025: After years of frustration with WordPress, I am finally abandoning this blog. The content will likely stay here for some time, but new content will appear here:

• jpw3.com

Normalization

In this context of composable and service-oriented applications, normalization refers to transformation of JSON. Normalization provides the advantage of insulating applications. Specifically, code that exchanges JSON and parameters directly with CMS Webservice APIs defeats the objective of decoupling solutions.

Code for the front-end of a website should use a normalized JSON representation of that data. Using files specifically provides the advantage that any consuming code has no dependency on the CMS itself or its interfaces. All code for accessing CMS Webservice APIs moves to processes for managing files and search indexes. Any code that writes to those files or search indexes normalizes data before storage.

CMS Consumption Phases

Applications typically consume content from the content management system during one or more of three basic phases in an application’s lifecycle:

• Build: Processes that build solutions can store content retrieved from the CMS anywhere, such as transforming JSON from Webservice APIs to static HTML files.
• Serve: Application server capabilities in the content delivery tier can invoke CMS Webservice APIs, such as while generating HTML dynamically.
• Consume: Client-side logic can invoke CMS Webservice APIs and update document object or otherwise interact with the browser.

Additionally, applications can retrieve data from the CMS through intermediaries. For example, applications often access search indexes that contain data retrieved from a CMS.

Considerations

The topics in this section explore some considerations relevant to the technique of storing JSON from the CMS as files.

Hierarchy

Many CMS solutions represent content as flat lists of entries of a given type, with no hierarchy. Alternatively or in addition, a solution could store JSON files in hierarchies, for example based on the paths in the URLs of the content entries that they represent or some metadata in the content. When the application receives a request, it could determine the corresponding JSON file from the path in the requested URL.

index.json

Storing data from the CMS as files provides an opportunity to manage additional files. For example, a triggered or periodic process could create an index.json file in each subdirectory listing the .json files in that subdirectory. Presentation elements could use these index.json files to generate navigation elements including visual sitemaps and breadcrumbs.

Maintenance

Generating, storing, and serving files requires resources. Where volumes are large, consider solutions that update existing repositories rather than regenerating every file, although every solution must typically include a complete regeneration process. For example, implement a process that uses CMS Webservice APIs to generate every required file, and then uses CMS publishing Webhooks to update that file system.

Maintenance processes may be complicated by events such as CMS entry deletion or where data (such as URLs) used to manage file system paths changes.

Except when normalizing or where values are exposed to users, use CMS entry IDs instead of URLs.

Normalization

By insulating applications, implementing normalization during file generation provides advantages at each consumption phase.

Performance

The local file system effectively serves as a cache for the CMS, which (discounting resources required to generate, manage, and serve files) can optimize runtime performance. If the application server needs content, it can access a local file system rather than waiting for a network call to the CMS. Clients use the same network path for JSON content as for HTML content.

Simplification

Discounting processes required to manage files, their use simplifies solution implementation, as every developer can easily read JSON from files without any need for proprietary knowledge of the CMS or even how to connect to it – just the (normalized) JSON format in use, which they can easily see.

Dependencies

This technique can also assist in cases where content entries depend on other content entries, which is often. Rather than placing Webservice API calls sequentially or requiring developers to pass parameters that cause inclusion of data from referenced items, using a local file system may provide performance sufficient to simply access items as needed. Normalization processes could also expand referenced entries, duplicating that referenced content and embedding it inline to replace the reference.

Costs

Depending on usage profiles and vendor pricing, using static files could lower costs by reducing the number of Webservice API calls to the CMS.

Failure Points and Troubleshooting

Removing the runtime dependency on the CMS removes a potential failure point and simplifies troubleshooting.

Static Sites

Excluding dynamic components that access systems other than CMS, entire solutions that use this technique exclusively could be exportable as static sites.

Security

Excluding cases where some content requires security, this technique can improve security by avoiding runtime access from clients to applications. The CMS can whitelist applications allowed to consume its content, such as file generation and search index maintenance processes.

Deduplication

Used effectively, this approach could reduce data duplication, especially in transmission.

Source Code Management

The JSON files could flow through source code management and version history.

Implementation

Obviously, don’t export data that you don’t need. The CMS may contain lots of data that the front-end doesn’t need or access as values in other entries, such as metadata tag definitions.

For environments that would allow it, compare performance accessing local file system relative to accessing files locally over HTTP, especially where the web server caches those files.

Accessing files instead of CMS Webservice APIs may preclude use of some CMS features and technologies including GraphQL.

Consider synchronization APIs if the CMS provides them.

Consider potential complications around previewing and other CMS features.

Disadvantages

Potential disadvantages of this technique include:

• Custom development to normalize and generate JSON files and potentially to manage the file system as source data changes.
• Hosting and administration of file system.

Conclusion

If you have any suggestions relevant to this topic, please comment on this blog post.