Skip to main content


What is headless?

Historically, the term “headless” comes from the hardware world to describe a computer that can be used without a monitor. Today it has evolved to mean anything where the user interface is separate from – or missing from – the processing logic.

floppy disk blue

There are a plethora of SaaS companies that are API only, meaning they have no user interfaces to manage the day-to-day functions of the system. They usually have administrative UI for adding users and provisioning the service but that’s about it. The rest of the integration efforts are up to the development team.

There are also hybrid headless solutions, like Searchspring, that offer headless API’s for some services, and fully UI-managed services in other areas.

Why is it useful?

As an analogy, let’s compare headless to Legos. Generally, when you buy a lego set, it comes in a box. On that box is a picture of the finished product, such as a Millennium Falcon. 

There are a couple of options for how you can build this lego set: 

  1. You can carefully build the Millennium Falcon by following the prescribed steps from Lego.
  2. You can take out all the Lego pieces and build anything you want – constrained only by the total pieces available.

Star Wars Lego Set

Headless APIs are the lego pieces that allow you to build anything else, only constrained by what each API allows you to do. 

The Searchspring search API is typically used to build out ecommerce stores that primarily run on mobile-web and desktop-web. That API could be used to build a phone native application. The search API could also be integrated with your email recommendations platform to generate dynamic listings when emails are opened.

Decouples UI from backend

This decoupling of the front-end from the back-end is a win-win for the company and the customer as it dramatically increases the flexibility to build novel solutions. Decoupling also allows you to open up the market you sell into and allows you to build your own UI.

API’s allow integration with other tools

Another example of tooling integration that Searchspring did not anticipate is the Search API being integrated with an internal SEO tool. The value of this was to have a list of SEM keywords and generate spreadsheets to analyze landing page results for these terms. Here, value is being created not for end shoppers, but for merchandisers using an API traditionally consumed for end shopper experiences. 

Why headless ecommerce?

A critical factor for why you should choose a SaaS solution with headless integration is that it allows you to differentiate from your competitors. If the UI is provided by the platform (say Shopify), even though it is templated, the websites all start to look the same. Shopify sites that utilize Searchspring’s headless Search API allow partners and customers to create amazing experiences for their end shoppers. One Searchspring client that that does an excellent job of attracting and retaining shoppers is Skims. Skims sets themselves apart and makes sure to give visitors to their site an excellent shopping experience. 

Prevents vendor lock-in

Another issue is what I like to call low-grade-everything. Platform companies have a lot to do around all the moving pieces of helping an ecommerce store flourish; from storing product data to logistics and shipping. Because of this enormous list of responsibilities they don’t spend enough time on specific high value elements of the shopping experience such as search and recommendations, for example. This is where merchants need to decide which pieces of the experience they want to pull out and delegate to specialized vendors.

Choosing vendors that support headless versions of these specialities allows ecommerce sites to perfectly tailor a shoppers experience to a specific theme and brand while adding value. I think we all know the disjointed experience where the recommendations product is an afterthought and shows up a long time after the initial page load. And there are other problems too. Even if the theme kind of matches, it’s slightly off. The hover effects don’t match the rest of the page, the call to action doesn’t glow, etc. Headless allows you to get this experience right.

Downsides of headless – You need a development team

The downside to headless is that it is you who is now responsible for its integration, design, development, and testing. Sometimes that knowledge is in house – and sometimes you’ll use a partner or the vendor if they have a white glove service available to help. 

So you accidentally built a tightly-coupled monolith?

Quite often, in the early stages of a company, speed is everything. In this haste, it is easy to overlook the important strategic advantage that starting headless provides, and you end up building a tightly integrated UI and Service logic architecture.  

Abstracting APIs

It’s worth noting that building a headless API and UI right at the beginning of a project is roughly the same level of effort as lumping it all in together, but pays dividends because you already have any easy way to provide headless APIs to your more advanced customers. You can easily build out a modern UI on top of your own APIs for customers that want an all-in-one experience.   Unfortunately, most people (myself included) don’t start out like that. Best-case, you end up with a monolith that is a three-tier architecture – nicely separating UI, business logic, and data storage. Worst-case it’s a PHP application with database calls right in the UI. Fun!

Strangling a monolith

In either case, you have an interesting knot to untangle if you wish to start offering headless APIs after your initial product has been around for awhile. Searchspring is currently pondering making all of our merchandising and reporting facilities headless which will allow:

  • Our merchandising to be integrated with a range of customer platforms.
  • Facilitate migrating rules, synonyms, and other functionality from legacy platforms.
  • Allow us to rebuild our merchandising UI to be smarter.

The  general pattern for rewriting a critical application is called the Strangler Fig, as proposed by Martin Fowler in 2004. This pattern allows us to incrementally replace and rewrite functionality transparently to the end-user without having to write a feature twice: Once in the new application and once in the legacy app – without having to do a big-bang release after a two year project is complete.