Headless web development: 6 things you need to know before launching your first project

Care to share?

Headless web development is a simple and natural concept that can actually make your architecture easier to understand and manage. This article will help you understand the very basics of headless development. It’ll share six insights with you on headless web development that will be useful in planning your first project. You can complement it with our other posts on headless transition and eCommerce platforms. The complete list is at the very end of this post. 

It’s meant for non-tech people. If you’re looking for a deeper level of understanding the technology, check out the articles written by Piotr Karwatka. I can personally recommend our eBook on designing a headless front-end framework for enterprise applications that sheds some light on how the modern front-end frameworks are being built.

What you need to know before starting a headless project

1. Headless architecture is actually more complex than monolithic.

It’s not the simplicity of the structure that you aim for with headless. The clean cut between the front and back end means that you actually have to maintain two standalone solutions instead of just one. It might contribute to higher maintenance costs and give you more server latency. If you develop both of them yourself, it also means additional work to wrap up all the endpoints and build APIs.

As Piotr Karwatka said in the Headless toolkit, with headless and microservices “the architectures aren’t getting any simpler, but the way they’re managed and accessed is.” At the price of additional complexity, you get agility. Instead of one complex monolith, you get two solutions that are easier to maintain, update, and replace. It allows you to cut operational costs and decrease the time to market. 

2. With headless architecture, the programming languages don’t limit you. You have a wide technological stack to choose from.

“One of the pretty cool examples of the shift is how eCommerce has evolved. Have you ever built an eCommerce store, maybe with Magento or Hybris, deploying huge java apps and exploring the domain-specific XMLs?

“Well, now, you’d use the Spartacus project, a Vue or React front end, and a simple REST API and deploy your app to Netlify within a few minutes. Of course, you’d have the entire CI pipeline on Github for free.”

Piotr Karwatka

Headless toolkit

The safest choice when it comes to programming languages for headless is JavaScript. It’s usually the first SDK provided by the headless platforms, and it’s a no-brainer when it comes to front ends. Most of the applications are built with Node, React, and Vue.

If you want to see some reference code, check out Strapi. It’s an open-source Node.js headless content management system (CMS) built with JavaScript. It can actually be a good base for your own system.

If you work with a boxed headless platform, they usually provide you with a couple of SDKs. For example, commercetools gives you JS, PHP, and Java SDKs to work with. 

But in the end, headless is tech agnostic. You connect through API, so you’re free to use any imaginable technology to power your solution. That’s another benefit of headless development.

3. The MACH stack is getting some real traction.

When we’re talking about headless development, it’s good to mention the MACH stack as a new standard. MACH stands for microservices, API-first, cloud-native, and headless architecture. It’s promoted by the MACH Alliance, an organization of software vendors, system integrators, and individual experts promoting this approach. Their vision is an open enterprise technology ecosystem.

MACH means: 


Microservices share the headless preference for splitting software up, but they take it to the next level. They are a result of splitting a monolithic platform into smaller parts with separate features that are easier to manage and replace. You basically split the whole software picture into a set of puzzle pieces to handle each of them separately.


When you split your application into microservices, you need them to communicate with each other. That’s when API comes into play. An API-first approach means prioritizing the service that the particular piece of software delivers. You start building the pieces by defining the API. It’s the first interface for your software.

If you’re interested in how it works, check out our webinar on the importance of API in the headless eCommerce platforms.


The MACH stack takes the weight of managing servers off your shoulders and moves it into the cloud. From an enterprise perspective, you outsource all the risks and challenges connected with owning your own infrastructure. It might make you dependent on the vendor, but building and maintaining your own infrastructure means a kind of dependency, too.


Decoupled front and back ends are natural complements of the MACH stack. This creates the flexible and easy-to-manage structure of the eCommerce platforms.

4. If you’re not sure if you need REST API or GraphQL, you can always choose both. 

REST API is a widely accepted standard for API communication. GraphQL is also a contender that aims to make API communication more efficient and economical, and avoid the flaws of REST.

In general, GraphQL has a brighter future. Some headless platforms are strong proponents of GraphQL. In fact, GraphCMS uses GraphQL exclusively. Others tend to stay compatible with both. 

Still, there are some that pick REST as a satisfying solution. For example, when you build a front end for Hybris, such as Spartacus, you have no other choice than to use REST API.

5. Face the buy vs. build dilemma, and solve it early on.

When we’re talking about developing headless apps, it’s essential to learn what solutions are already available on the market. The new platforms very often gravitate towards composable commerce. That means that they are easy to adapt and plug into your solution, and you don’t have to build every feature from scratch.

When you build something, you have to maintain it. If you buy something within the MACH stack, you probably don’t even have to host it because you get the complete solution in the software-as-a-service (SaaS) model. You can find an interesting reference to that problem in the Headless toolkit.

Most of the time, the best choice will be to get a platform and extend its possibilities through custom development. When you choose this path, you have to carefully pick the basic platform.

“[With headless], it’s easier to change the platform because it’s, well, ‘just API.’ You can find a replacement service. The motivation though, given all the integration work already done, is very small if the platform of your choice is scalable enough and flexible enough.

“That’s why choosing an eCommerce platform, which is now more like the ‘glue’ between all the other architecture puzzle pieces, is more important than ever.”

Piotr Karwatka

commercetools – Composable Commerce, Reference Architecture

6. Remember that you can always call for help

Of course, if you need a hand with your project, you can always count on our team. Some amazing projects that are storming the market right now were actually born here at Divante. Vue Storefront, Open Loyalty, and Meetsales are three of them. 

We can help you build any product from custom software solutions and PWA storefronts to eCommerce platforms. 

Simply contact our team at Divante, and they will take care of your project from there.


Additional free resources on headless development

We’ve created plenty of eBooks and blueprints on headless at Divante. If you’re up for some more data, you can start with our Headless toolkit. It’ll introduce you to the world of headless commerce and present some of the top solutions available on the market:

New call-to-action

But wait, there’s more. Check out those free eBooks:

This post is a part of a longer series on headless eCommerce. You can see the rest here:

Published July 21, 2021