Headless architectures enable a decoupled approach to web and app development, i.e., it allows content and services to be mismatched and shared across different channels or heads while being perfectly interoperable. With a proper headless architecture, you can also build a centralized repository of reusable services within your organization.
Compared to a monolith approach, decoupling everything will also sophisticate the architecture and will force you to make more decisions. You are going to have to select different technologies and services, but that’s for the greater good, and the inherent challenges can be easily resolved by being pragmatic, with good anticipation and best practices.
What Is Headless Architecture?
The pure definition of Headless refers to a system or software that can run without a graphical user interface (GUI). This means that the system can be controlled and accessed remotely without anything being displayed.
Does that ring a bell? Microservices? APIs? Yes, 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 fully consume and control those data via APIs as well.
The headless architecture is the combination of many different headless services connected to each other 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 made 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 Frontend(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, as well as easier integration with other systems and platforms.
For example, if you have your Frontend powered by Next JS running on Vercel and your content in Contentful, you have a headless architecture. The 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
- 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, once the payment service charges the buyer and the payment is successful, what do you do? 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. That third layer, despite being optional, is anticipated to be your own headless service(s) that you implement. To glue the services together, a layer of shared internal services handles syncing between the stack services and operations, such as authentication, order intake, or payment. And following the same logic, your Service API is a layer as well. 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 headless frontend framework or modern approach to web development like Jamstack, for example.
- 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 true composable commerce approach.
- Easily share services across all channel heads.
- Innovate and experiment with new channels, i.e., enable a true omnichannel presence for your business.
- Better performance out of the box.
- 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 below diagram:
Headless Architecture Diagram
Let’s go into detail. The following diagram shows that some services cannot communicate directly with the heads. Indeed there is a layer of control/security/remapping/conversion/ etc. that happens thx to the Service API (more about it below).
Channel Heads, AKA Frontends
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 that will 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, and Platform.sh, Gatsby Cloud, or Cloudflare pages or directly on a lower-level cloud platform as services such as AWS, Azure, or Google Cloud.
Get a head start in headless 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 for you to build a tailor-made shopping experience for your headless commerce business.
Headless API Services
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 have the freedom to build the best-of-breed stack that fits your business as opposed to shoehorning your business needs into a monolithic single-vendor architecture.
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 full CMS or not a full 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 all point out 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. Plus, you don’t wanna be caught off guard by any 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 it MUST work seamlessly with your other systems and services.
Special note on Webhooks: Webhooks are keys in a headless architecture.
In 2023, your architecture must be real-time and performant, which means asynchronous. A webhook is an HTTP Callback. It’s a notification that is 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 done.
- 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.
Middleware: Service API
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. Practically 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 they should simply translate requests between services. The service API is typically hosted on a dedicated service for serverless hostings, like Vercel, Netlify, Heroku, or AWS.
And let’s have a complex example here to show the power of such architecture using Webhooks.
It’s clearly visible here that the Service API is just the connector. That’s the central part (that can be decoupled, too) that is going to map the data from one system to another. It acts like a smart proxy, but it does not own any complex logic.
User experience and conversion are directly affected by page speed, and one of the biggest 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 (just take a 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 tougher than with traditional monolith solutions.
Here are some best practices and tips for managing such a platform:
- Performance. It's important to ensure that the APIs are performant and able to handle large amounts of traffic. Monitor the performance of your APIs and make changes to the architecture as needed to ensure that they continue to perform well.
- Documentation. That will be important 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 that the architecture continues to function as expected.
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, make sure you can work on your frontend + service API locally (or on Github Codespace!) and replicate the architecture using Docker or Vagrant.
- Automated tests. You need to reduce the feedback loop, and you need to detect as soon as possible crashes or bugs in the development workflow.
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.