Git-based CMS vs. API-driven CMS: Which Headless CMS Should You Choose?

While the world is shifting to the cloud, web content management systems (CMSs), the most popular ones at least, are still stuck in 20-year old technologies and architectures. This was the intro to this post 2 years ago and funny enough not much has changed.

Whatmore, Wordpress for example (released in 2004) powers 41.5% of all the websites on the internet right now (an increase of almost 5% from 2 years ago).

Still, the demand for innovation and a better digital experience that’s grown immensely in recent years accelerate the adoption of modern frontend tools to create lighter, faster, more secure sites. But also pressured popular solutions to go that road as well (did anybody mentioned headless WordPress!?).

A simple reason for that really. Headless CMSs focus solely on managing content and providing a great content editing experience while empowering devs to use whatever front-end and back-end tech they want in order to make better websites.

Now, rather than going through the explanation of headless CMS and its ecosystem (which we did with an opinionated post that got us into trouble, click the link) in this post, we’ll cover the two types of headless CMSs, the Git-based CMSs, and API-driven CMSs. The differences, the challenges, and the benefits of using them.

Git-based CMS

With a Git-based CMSs act as a layer on top of Git and are interacting directly with Git repo. Basically, you are working with files stored in your Git repository. Let’s take a look at the pros and cons of these CMSs.


  • Full version control on all content out of the box.
  • All content is present as flat files so developers can use all the tools they typically use.
  • It is easy to roll back.
  • This is the most homogenous approach for most web developers thanks to the existing git-based workflow.
  • No bandwidth or data caps
  • No vendor lock-in.
  • Simple setup.


  • If you want to use several apps or sites to pull content from the same CMS, a git-based option might not be the best solution.
  • If your site has tons of content, you may want to look into the database instead.
  • If you plan on changing content rapidly, like new posts every minute, the Git-based option is not the best option for you.
  • Limited options. Less control over content model and formating.
  • You need a separate service for media files (repo size limits).

API-driven CMS

API-driven CMS or API-first CMS or API-based CMS is a headless CMS that serves your content via an API, typically a REST API or GraphQL, allowing you to have your content completely decoupled from the presentation. So, you are getting your data and the way it is structured but it depends on you to choose which framework and language you will use to work with it.


  • This is the best solution if you have several different apps or websites that pull the same managed content.
  • Easy to use content with multiple front-ends.
  • Most available options give you the ability to customize CMS completely to your liking.
  • You can handle huge amounts of data easily.
  • Asset management. Unlike Git solutions, most API-driven products come with the ability to upload and manage assets.


  • This version is not controlled in Git and it is also not integrated into developer workflow as git-based CMS. Now, although this is more of a difference in architecture and approach, some people take it as a downside. We’re just making you aware of it.
  • Usually comes with storage and API usage limits. It can be costly if you don’t plan things well.
  • Dependency on devs for bigger changes.

Now that we got that out of our way, let’s take a look at the benefits and disadvantages of each of these systems one should keep in mind when choosing a headless CMS for your next project.

[@portabletext/react] Unknown block type "newsletter", specify a component for it in the `components.types` prop

The benefits of Git-based CMSs

Multi-object versioning

Traditional CMS platforms such as WordPress for example, have limited versioning which means they either track single object graphs or maintain clunky data structures (especially when used with complex visual builder solutions).

Nothing wrong with this approach for basic content management needs, for example, for blogs or very simple websites. But not for a multi-asset digital experience which is a necessity for most brands nowadays.

The multi-object versioning approach, one backed with a Git-based solution, allows for a more specific content change tracking. And with the content being stored as files it is easy to move it among environments (Test, Dev, Production, etc.) and migrate between systems.

Distributed repository and branching

Contrary to traditional CMS models, Git allows developers to have their own local and intermediary Git branches, all born from a parent repository.

Distributing the versioning and workflow is fast and easy!

With the Git-based system, devs can work locally and still be part of the CMS. This means that the devs can use the tools they prefer and work with daily, with no restraint.

And thanks to branches you can create previews and almost unlimited staging environments which make development easier in general. Both developers and authors can experiment and work on major features and site enhancements.


Because your data is in local files, committed to your git repository, you are de facto the sole owner of your content and you are free to move from one git-based CMS to another easily.

The benefits of API-first CMSs

Existing ecosystem

With the ease of integration being a huge part of the popularity of the API approach the growing ecosystem can be a tipping point when choosing a CMS solution. The approved solutions enforce best practices and use the appropriate endpoints in the API minimizing error potential.

For example, brands can freely integrate their most liked marketing tools such as marketing automation, CRM, and analytics but also. They can also remove them at any time. This gives brands the ability to quickly change their digital experience platform the way they see it fit.

Reach out to consumers on several different devices

IoT devices are taking over our everyday life and more and more people are turning to them for the news, shopping, tasks scheduling, search the web, etc.

Traditional CMS platforms are not able to deliver customized experiences on all devices but an API-based CMS can. All brands need to do is simply develop an API for that device or touchpoint and then plug it into their stack.

There are absolutely no restrictions on what device you can deliver the experiences.

Faster content repurposing

With API-based CMS, all the content is stored centrally which enables brands to deliver their content to any channel. This means that the content creators can write their content once and then repurpose it for any channel or device. In the omnichannel world of today, this comes as a huge benefit as it saves a lot of time and removes the need of having to create content for each channel separately.

The challenges of Git-backed CMSs

Relationships in Git-based CMS

While often overlooked or rather taken for granted Relationships are hugely important for modeling content and keeping it in check. The main issue with current Git-based CMS solutions is that they are very brittle as explained here.

Special measures for SEO will be necessary

Git is not known as an SEO-friendly solution for a long time since there was no specific support for improving SEO. To have better visibility, you’ll need to take some steps such as generating a sitemap, using metatags and open graph tags, and also making sure to have a mobile-friendly theme.

GitHub doesn’t run plugins

Github is known for not running plugins. If something needs to be customized it can be easily mitigated by pushing locally generated content.

The challenges of API-based CMSs

Too reliant on web devs

Need to create custom front-end on API-based CMS creates additional work for your team. This will also require constant communication between marketing and web dev teams for any changes that need to be made.

(For some) Content preview is a problem

API-driven CMS solutions come with a back-end editor that allows content creators to input their content. However, there are still CMSs that do not allow you to preview your content before you publish it or the draft option is something you have to set it out yourself. No being able to see how the pages look and feel from the users’ side is often a disadvantage as it leaves little to no room for mistakes.

The costs

There are certain costs that you’ll need to keep in mind with the use of API-first CMSs even the open-source ones. This includes infrastructure costs (hosting, CDNs, etc. for self-hosted CMSs) but also development, maintenance, and security costs since you’ll be working on a custom-made back-end.

Git-based or API-driven CMS, which one should you choose?

No easy answer here. The main difference between the two is about the content ie how the content is stored, and how it is consumed. That fact alone should be a driving force when deciding which one to go with.

For example, we’ve found that if you don’t need to create hundreds of posts/pages and rebuild the website very often, Git-based CMS is a far better and cheaper option. On the other hand, if your project demands easier scaling and an easy-to-use publishing feature API-driven CMS is for you.

Today, every project requires a certain level of customization unique to it. The best you can do is make sure you understand the scale of the project, budget, available dev time (yes, that’s an actual requirement), and the tech behind it before making a decision.

Or opt-out for a web dev shop like Bejamas that can help you connect the dots and make them work. In fact, we can do much more than that.

Need a web dev team to back your ideas and bring them to life with modern tools? Let’s talk.

BOOK A MEETING today and learn more about what we can do for you and your business.

List of Git-based CMSs

Forestry - - Take a look at our Forestry review.
Crafter CMS -
Decap CMS - - Take a look at our DecapCMS review.
Publii -
Prose -
FrontAid CMS -

List of API-driven CMSs

Storyblok - - Take a look at our Storyblok review.
Contentful - Take a look at our Contentful review.
Sanity - - Take a look at our Sanity io review.
Dato CMS - - Take a look at our DatoCMS review.
Prismic - - Take a look at our Prismic review.
Ghost - - Take a look at our Ghost review.
Strapi - - Take a look at our Strapi review.
Kontent - - Take a look at our Kontent review.
Directus - - Take a look at our Directus review.
ButterCMS - - Take a look at our ButterCMS review.