Headless vs API-first

Headless and API-first - two sides of the same coin? Or not?

The MACH architecture has been gaining significant traction among vendors in the commerce space. MACH stands for Microservices, API-first, Cloud-native, and Headless. When examining these principles, it becomes apparent that a solution can be headless but still monolithic, meaning it doesn't follow a microservices-based structure. Alternatively, a solution may be headless but not fully embrace cloud-native technologies. Similarly, a platform can be cloud-native but not organized around microservices.

However, the more intriguing question is whether a platform can be headless without adhering to an API-first approach, or conversely, if it can be API-first without being fully headless. In this blog post, I will delve into these two concepts, explore their relationship, and provide real-world examples to illustrate these distinctions.

Getting the definitions straight

The concept of "Headless" in architecture refers to the decoupling of the front-end presentation from the back-end logic and infrastructure, allowing it to remain independent of specific channels, programming languages, and frameworks. Nowadays, numerous vendors position themselves as headless, including Bold Commerce, commercetools, Shopify, BigCommerce, VTEX, Spryker, Magento, Salesforce, Elastic Path, and others. Almost any commerce vendor that offers APIs will claim to be headless, making it a widely adopted term in the industry.

On the other hand, "API-first" is characterized by the approach of exposing all functionalities through APIs. It represents the underlying philosophy with which a solution is built. The key question is whether the solution is primarily designed to be utilized through APIs or not. This point is where commerce vendors often diverge. While some vendors may position themselves as headless, they might not truly embody an API-first solution in their core architecture.

So what does it mean to be API-first in practical terms? And is it essential for a solution to be both Headless and API-first, or maybe being Headless is good enough?

What does it mean to be API-first?

The textbook definition of "All functionality is exposed through an API" may seem straightforward at first glance, but it harbors complexity. What exactly constitutes "All functionality"? For instance, a platform might offer API access to pull a cart by its ID but not by a customer ID. This ambiguity leads us to consider two types of API coverage within the API-first context: whether specific functionalities are covered through APIs or not.

A crucial aspect of being API-first is whether a platform places any restrictions on how its APIs are utilized. The answer to this question is either a definitive "Yes" or "No." For a platform to genuinely be considered API-first, the answer must always be a resounding "NO." There should be no room for uncertainty or conditions.

Two key metrics come into play to assess API-first status:

Absolute API coverage: This metric reflects the percentage of functionalities available through the platform's UI that are also exposed through APIs. While it indicates the extent to which the solution embraces APIs, it may not directly address specific use cases. An ideal API-first platform strives for absolute API coverage as close to 100% as possible. In fact, some platforms may even offer more capabilities through APIs than their UI, further demonstrating their API-first approach.

Relative API coverage: This metric gauges the percentage of your specific use cases that are supported by the platform's APIs. While it's a relative measure and doesn't solely determine API-first status, it is of great importance since it directly impacts whether the APIs cover the functionalities required for the use cases you intend to build. Ultimately, if a specific platform falls short in supporting the use cases you desire, other considerations become irrelevant.

To be rightfully acknowledged as API-first, a platform must adhere to two fundamental principles: it must not impose any restrictions on API usage, and it should boast high absolute API coverage. Embracing these principles ensures that the platform genuinely prioritizes an API-first approach, providing developers with the freedom and comprehensive functionality they need to build innovative solutions.