Understanding Headless Architecture: Benefits, Use Cases, APIs, Best Practices and Challenges

Headless refers to a system or software that can run without a graphical user interface (GUI). This means the system can be controlled and accessed remotely without displaying anything.

Headless architecture is a concept that marks the separation of the front end (user interface) from the back end (business logic) of the website.

Does that ring a bell? Microservices? Kind of. The concept of microservices is much broader than headless.

What about APIs? A headless service is a service that has APIs (Application Programming Interfaces). Nowadays, on top of those APIs, headless services also tend to provide a UI to manage the data they control, but you can entirely consume and control those data via APIs as well.

The headless architecture combines many different headless services connected via APIs. It’s also called the best-of-breed approach because you can pick and choose the services you prefer in your architecture and evolve and change your mind along the way.

The main goal is to decouple everything. This means that all the components are designed to operate independently of each other, with minimal or no dependencies between them. This allows for greater flexibility, scalability, and maintainability, as changes to one component are less likely to affect the others.

There are usually three decoupled layers:

• The headless service(s) (backends) that provide value out of the box: Payment, Auth, eCommerce, CMS, Emails, stats, etc.
• The Heads (channel head): the front (s) that provide the presentation layers (UI).
• And an optional but most likely required middleware that contains the business logic and acts as a glue between them all.

This approach allows for more flexibility and scalability in building applications and easier integration with other systems and platforms.

Let's say you have your front powered by Next JS running on Vercel and your content in Contentful. That's a classic headless architecture there, and the main point is you can easily change any of them (Next JS, Vercel, Contentful) independently.

But that’s a simplistic approach. In a headless eCommerce environment, you’ll probably have the following setup:

• One or more frontends (for catalog, checkout process, accounts pages could be decoupled, etc.).
• One or more authentication service(s).
• One or more payment service(s).
• Crystallize baking your product storytelling completely (that wraps up all of the below), or
  • One service for eCommerce;
  • One as PIM service;
  • One as CMS service;
  • One as DAM service, etc.
• An Email service.
• A Tax Service.
• Possibly an ERP system.
• Customer Relationship Management (CRM).
• And more, if needed.

And unlike with the simplistic approach, it is expected that you will need the third layer, the service API (middleware API).

Following the ecommerce example we’ve mentioned, what do you do once the payment service charges the buyer and the payment is successful? Which service is responsible for pushing the Order to a specific stage? Even simpler: how to manage/control the prices for your B2B, authenticated users?

Most likely, you won’t be able to find the perfect set of services that do everything for you because you run a unique business. Despite being optional, that third layer is anticipated to be your own headless service(s) you implement. A layer of shared internal services handles syncing between the stack services and operations, such as authentication, order intake, or payment, to glue the services together. And following the same logic, your Service API is also a layer. It could be more than one service responsible for one thing only.

The benefits of this type of architecture are:

• Relying on APIs to pass data from backend business logic services to the frontend presentation layers makes it secure and fast.
• Freedom to use any frontend framework or modern approach to web development like Jamstack, for example.
• Faster time to market on any channel and update/change the front end independently of the services you use.
• Build a stack of best-of-breed services that precisely fit your business needs—a genuine composable commerce approach. Or change the ones not working for your business case just as easily.
• Easily share (or not) services across all channel heads.
• Innovate and experiment with new channels, i.e., enable an actual omnichannel presence for your business.
• Better performance out of the box (we'll talk about it a bit later).
• Streamlines workflow. Allows teams to iterate and deploy new functionality fast.
• Interoperability between services and team splitting: you can have a team that manages the checkout process in GoLang and a team that manages the catalog in Next JS.

When you select Crystallize as your product story engine, all of the services above are included, managed with a single API as shown in the diagram below:

Let’s go into detail. The following diagram shows that some services cannot communicate directly with the heads. Indeed, a layer of control/security/remapping/conversion/ etc. happens thx to the Service API (more about it below).

The head(s) in headless are presentation layers, where you build your tailor-made storefront, website, or app. The frontend responsibility, ideally, is to display content and enable navigation and search for your customers. To deliver a compelling product story to help them find, explore, and purchase the products and content of interest.

Following a headless approach allows flexibility to build the front ends in your favorite framework and host it on your hosting provider of choice. The most popular modern-day frontend technologies are React, Vue, NuxtJS, NextJS, GatsbyJS, React Native, Remix Run, Astro, and Svelte, to name a few.

The frontends are typically hosted on modern static hosting services like Vercel, Netlify, Platform.sh, or Cloudflare pages or directly on lower-level cloud platforms such as AWS, Azure, or Google Cloud services.

Get a head start over your competitors with our free and open-source boilerplates. They are production-ready solutions using one of the mentioned frameworks, tuned for performance, and a great starting point to build a tailor-made shopping experience for your headless commerce business.

The headless API services are the backend of your headless stack. The toolbox that you use for your Internet craftsmanship. By choosing a range of services, you can build the best-of-breed stack that fits your business instead of shoehorning your business needs into a monolithic single-vendor architecture.

Traditionally, eCommerce platforms employed monolithic architectures where the front-end and back-end were tightly integrated. This structure, although robust, often became an impediment to rapid adaptation to market demands. The transition to headless architectures in eCommerce elucidates a shift towards a more modular, scalable, and performance-optimized approach, empowering businesses to adapt swiftly to evolving market dynamics and technological advancements.

Selecting the right services in your stack of headless services is crucial. You will have to research, test, and evaluate different available services. The main goal is minimizing the ToC (Total Cost of Ownership). The following suggestions can help you in making the right decisions.

• Feature set. Find a service that does what you need and not necessarily everything. You don’t want to end up vendor-locked. It might be the hardest thing to do. For example, you probably don’t need a full DAM but just an Asset Organizer—or not a complete CMS or PIM. Or maybe you do. Either way, it’s totally fine to handpick service and embrace the best-of-breed approach.
• Reputation. Customer feedback, industry recognition, and financial stability point to choosing a reliable partner for your business.
• Pricing. Budget planning matters big time. Long-term sustainability of the pricing and licensing offers peace of mind. You don’t want to be caught off guard by hidden or additional fees.

• Performance, reliability, security, scalability: those boxes MUST be checked to achieve success.
• Support. A headless service MUST offer above-average support. It loops back to reputation.
• Webhooks. Last but not least, the service you pick MUST be flexible and customizable and work seamlessly with your other systems and services.

Special note on Webhooks: Webhooks are keys in a headless architecture.

In 2024, your architecture must be real-time and performant, which means asynchronous. A webhook is an HTTP Callback. It’s a notification triggered by an event from a headless service to another that you define.

Webhooks in headless architecture are the cornerstone of interoperability. For example:

• Your payment service calls your Service API to notify you that the payment for that Order ID is made.
• Your CMS/PIM service triggers a rebuild of your static website (or a cache purge event) when content has been updated.
• Your OMS service calls your CRM to push data on Order Creation.
• Your OMS service calls your Email service to send a transactional email.

As mentioned, the service API is the glue in your headless architecture. It links all the different stack services and handles parts of the business logic, such as handling payments, authentication, etc. Again, any server-side technology you are familiar with can be used to build the service API, such as  NodeJS, Golang, or Ruby, and exposed via a simple GraphQL or REST + JSON API.

The individual services of your Service API are typically implemented serverless for simple horizontal scalability with increased traffic. This is where you connect your API tokens and data from your visitors with the headless API services. E.g., collecting the payments from Stripe callback, creating orders in Crystallize, and sending a confirmation email using SendGrid. The glue for your business.

API services should ideally not persist data and translate requests between services. The service API is typically hosted on a dedicated service for serverless hostings, like Vercel, Netlify, Heroku, or AWS.

The service API can easily be used across all your channel heads. For example, the order confirmation email service can be used in your Next JS eCommerce and React Native eCommerce App.

In our open-source section, you can find everything about the Service API boilerplate, built on NodeJS and deployed on various hosting providers in our open-source section.

And let’s have a complex example here to show the power of such architecture using Webhooks.

It’s visible here that the Service API is just the connector. That’s the central part (that can be decoupled, too) that will map the data from one system to another. It acts like an intelligent proxy but does not own any complex logic.

User experience and conversion are directly affected by page speed, and one of the most significant benefits of going with headless architecture is the better performance of your pages. In the speed-obsessed world (and Google), every second matters, and going headless is a shortcut to the results (look at the performance data of this page).

Going headless is not without its challenges. With the workflow of headless architecture being more developer-centric, you (or your team) will need more technical skills to work with it. And with a growing number of headless services, decision-making can be more challenging than traditional monolith solutions.

Here are some best practices and tips for managing such a platform:

• Performance. It's vital to ensure that the APIs are performant and can handle significant traffic. Monitor the performance of your APIs and make changes to the architecture as needed to ensure that they continue to perform well.
• Documentation. It will be necessary for all team members to have a good overview of the responsibilities of each service and how they work together. This can be particularly helpful as your team grows and new members are added.
• Innovate. Best-of-breed means decoupled, which means you can innovate on specific/select services and let your team use different frameworks and tooling.
• Security. Consider the security implications between the components and ensure that sensitive data are properly encrypted and transmitted over secure channels.
• Monitor. (and test) CI/CD Continuous Integration and tests are crucial to ensure the architecture continues functioning as expected. Adequate testing is mandatory to identify and fix errors early in development.

From a developer perspective:

• Use a mono-repository for your code: decoupled services do not mean decoupling the code. Ease the development, the DevOps, the maintenance, the visibility, and the collaboration by centralizing and sharing the maximum you can.
• Besides the Headless services, ensure you can work on your frontend + service API locally (or on Github Codespace!) and replicate the architecture using Docker or Vagrant.
• Automated tests. You must reduce the feedback loop and detect crashes or bugs in the development workflow as soon as possible.

There are no cutting corners on either of these. Still, dev-friendly solutions, much like Crystallize, can help you go to market faster with a tailor-made solution for your business.

The obvious challenge is increased complexity due to the separation of concerns, which is the potential for more errors, especially if teams collaborate poorly or misinterpret specifications. Going the headless way also requires more extensive testing and potential error-fixing on top of API version management. Challenges are mainly on the side of your dev team and their proficiency in the tech stack of your choice.