Approaching SaaS Headless CMS Projects

This blog post lists some questions to start conversations while evaluating architectural requirements for SaaS headless content management projects, which typically include one or more websites. This post is not specific to any individual CMS and much of it could apply to any modern connected system, but I work for Contentstack and so emphasize relevant terminology in some places. If you have any suggestions to add to these lists, please comment on this blog post.

A successful CMS implementation prioritizes and balances customer requirements against resource constraints, of which development time is often primary. Before implementation, reviewing questions such as the following with anyone involved in the CMS can help to gather potential requirements. Help the customer understand the need to plan for potential future needs while minimizing initial expectations, especially anything that involves custom development, and then architect the solution appropriately.

  • What are the core goals and requirements of the solution, including expectations based on sales demonstrations, POCs, training, and experiences with other systems?
  • What is the chosen CMS, and for what primary reasons?
  • If there is a legacy CMS, what are the main reasons for its replacement?
  • What is the existing development process, and will it change with the new system?
  • Who are the parties involved in the implementation?
  • What are the main websites, user interfaces, applications, and other solution deliverables?
  • How often are new sites or other significant components of the solution created?
  • What are the lifespans of the various components of the solution?
  • What are the requirements for media?
  • What are the organization’s preferred development, scripting, source code, ticket, build, and other tools and technologies?
  • What hosting and programming technologies will the solution use for content delivery?
  • What is the size of the solution?
  • What are the requirements for internationalization and localization?
  • What is the information architecture of the solution?
  • What is the search solution, and what are the intentions for its use?
  • What is the strategy for defining and managing URLs, including redirects and vanity URLs?
  • What additional solutions, such as internal systems, media, streaming, commerce, social, experience management, and otherwise need to integrate with content management and content delivery, and in in what ways?
  • What are the known project deliverables, when are they due, who is responsible for each, and what is their state now?
  • How should preview, workflow, staging, and publishing work?
  • Is there an existing volume of semi-structured or better content worth attempting to migrate automatically?
  • Should visitor traffic interact with CMS, search, and other vendor platforms directly, or though services managed by the organization?
  • Will this solution involve an enterprise message bus?
  • In what cases would the organization use the vendor’s SDKs and in which would it call the HTTPS APIs directly?

In CMS, data modeling may be more fundamental to success than development. Mapping the information architecture and other known requirements to optimize content types used by the organization’s users to enter data is a skill and an art that takes some experience. To improve usability, try to minimize the number of content types and references between entries. Content types are flexible and easy to create and define. If possible, have the eventual CMS end-users evaluate prototype content types before committing to a specific strategy.

Apply vendor-specific content modeling features such as reusable structure definitions (Contentstack global fields), repeating fields (Contentstack multiple fields) and groups of fields (Contentstack groups), and nested flexible data structures (Contententstack modular blocks). Try to balance the data model to facilitate both CMS users and developers. Focus development resources on the content delivery environment (the published website) rather than the content management environment (customizations to the CMS).

While determining the content types, required fields, and field properties, identify where each CMS facility is most appropriate, specifically for integration with other systems.

  • Content Management API: Import, update, workflow, publish, and otherwise manage content.
  • Content Delivery API: JSON CDN of published content with query facilities.
    • GraphQL API: JSON CDN of published content with query facilities.
    • Synchronization: Initialize and then retrieve batches of updates.
  • Media Delivery API: Including server-side image manipulation and optimization.
  • Custom User Interfaces: Consider needs at the field, entry, and dashboard levels of the CMS UI.
  • Webhooks: External systems respond to event notification from the CMS.

Certain patterns emerge:

  • Custom field types can select data from external systems, such as a value from a selection list, the identifier of a product, or a more complex user interface consisting of multiple nested fields.
  • Webhooks and/or polling and/or custom UI components can trigger synchronization APIs such as to build or update a search index, clear caches, and otherwise manage data replicated into other systems.
  • A webhook listener can publish CMS events to an enterprise message bus with subscribers that trigger additional functionality.


Leave a Reply

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

You are commenting using your 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: