What is an API-Based CMS?

If you know what an API-based CMS is, skip this section.

The typical way to build a CMS-powered website is to choose a fully-integrated solution like WordPress and build your website as a collection of tightly embedded templates. Or if you want more control, you build your own integrated CMS using your preferred tech stack.

An API-based CMS, also known as a headless CMS, is a relatively new approach to content management with many advantages over the “old” way. API-based CMSs, such as ButterCMS, CloudCMS, or Prismic, allow you to build websites and apps that are decoupled from their content management tools and integrated via API. This gives you the flexibility to build your front-end using your preferred tools (eg. Rails, Node.js, Angular) while being able to integrate a customized, robust CMS with ease. An API-based approach can save a team significant time and money in the initial implementation as well as ongoing maintenance.

Navigating the Choices

So you’ve decided that an API-based CMS is right for you, so you pull up Google and start exploring the options. You find dozens of different CMSs selling the API-based approach and offering all kinds of features and add-ons. You come across SaaS options charging upwards of a $1000/mo, abandoned open source Github projects, and confusing terms like content objects. You also find articles about WordPress’s API, and using Drupal with separate front-ends.

How do you begin to make sense out of all this? We’ve created this guide to help.

Breaking Down the Categories

API-based CMSs are a confusing beast. Some new products call themselves API-first, whereas many others have evolved to offer an API-based approach.

For example, WordPress recently rolled out a REST API and maintains some client libraries, such as node-wpapi. Similarly, Drupal 8 includes a RESTful web services API. Using these APIs, you can integrate any front-end with a WordPress or Drupal instance. Let’s call these traditional providers.

On the other hand, API-first SaaS offerings like ButterCMS and CloudCMS are built solely around API integration. To go even further, different API-based CMSs are built with contrasting API design styles. For example, ButterCMS has a RESTful API with token authentication. CloudCMS uses OAuth, some products privilege XML instead of JSON, and some, like Hygraph (formerly GraphCMS), are designed around GraphQL.

Example of the ButterCMS admin interface

So, considering traditional vs. API-based, what’s the better approach?

It depends. Both options work. If you’re familiar with a traditional open source solution like WordPress or Drupal, leveraging their APIs for front-end freedom may seem attractive. But ButterCMS and CloudCMS are designed for the API-based approach and offer a better developer experience.

For example, WordPress offers official API clients for only two languages and no official guides. ButterCMS offers API clients for seven languages and over a dozen guides for various frameworks.

Traditional providers like WordPress can also be severely limited in their flexibility and customization when integrated via API. This sounds surprising, since WordPress powers 27% of the web and is known for its rich, mature ecosystem of plugins that allow you to build anything from a massive publishing website to an eCommerce store.

The problem is that most of the WordPress ecosystem does not address API usage. For example, to enable custom-fields in WordPress requires a plugin and a self-managed WordPress instance. But once the plugin is setup and custom fields are created, there’s no documentation on how the custom fields would be fetched over an API. Underscoring this problem is the existence of yet another plugin called WP REST API Custom Fields that aims to solve this. However as of the time of this writing, that plugin hasn’t been updated in over two years.

In cases like this, the plugin-based extensibility of traditional providers like WordPress become useless and potentially impossible to work around. API-first solutions, on the other hand, are built from the ground-up to support flexibility and customization. For example, ButterCMS not only allows you to create custom content models and fields, it even allows you to customize the admin UI into user-friendly workspaces.

What API-based CMS solutions lack in available plugins, they make up for by integrating into a codebase and tech stack you fully own and understand. This means you can drop in other useful open source plugins or Backend-as-a-Service providers as you need. For example, you can combine an API-based CMS with an API-based eCommerce backend like Moltin to build a complete eCommerce website without a database (or even a server!).

Hosting vs Self-hosted

Another consideration is whether to manage hosting yourself or not.

As mentioned earlier, with traditional providers like WordPress, self-managed hosting may be your only option if you want to customize your CMS beyond default settings. When considering self-hosting management, remember you’re not just dealing with hosting fees, but moreover, full responsibility over making sure your website stays online and is secure. This includes database maintenance and backups, installing security upgrades, and having server monitoring systems in place.

Chances are, your development team doesn’t enjoy spending their time backing up databases, setting up hosting, installing upgrades, and being responsible for monitoring content management system uptime. Going with a hosted solution means you are almost 100% freed from any type of maintenance.

With API-based CMSs, self-hosting is an option (eg. CloudCMS offers this), but hosted offerings are more standard. The benefit of this approach is that you never have to worry about maintenance or uptime for your CMS. You get to build your website and move onto more important things.

Understanding Pricing for Headless CMSs

When looking at SaaS providers there are four key areas that impact pricing:

1. Amount of content you can manage
2. Number of API calls allowed
3. Number of user accounts
4. Uptime

Different products use different terms in their pricing plans, but generally it comes down to these four criteria. For example, ButterCMS offers unlimited API calls but caps on the amount of content, whereas CloudCMS offers caps on API calls but an unlimited amount of content. Simple, right? Also consider add-ons that you might care about such as publishing workflows, localization, and webhooks.

One important factor to look at is support. When your team runs into a time-sensitive problem, quick assistance from a knowledgeable support engineer is hugely beneficial. API-based CMS providers are popping up all over the world, so in addition to responsiveness, consider timezone and language barriers that could affect communication.

Another thing to pay close attention to is uptime – with an API-based approach, your website is highly dependent on your CMS API. In most cases, if your CMS’s API goes down, so will your website as it will be unable to fetch content. For this reason, ensure a near 99.99% uptime level guarantee from the vendor, and do proactively prevent data loss scenarios. For example, the ButterCMS Ruby client offers the ability to setup a local fallback datastore such as Redis so that your website functions even if it cannot successfully connect to the ButterCMS API.

For larger projects, you may be interested in enterprise-level service level agreements and white-glove support such as working directly with a solution engineer from the vendor.

Evaluation Checklist

We’ve covered a lot of information thus far. Even armed with this knowledge, making a decision is difficult given the sheer number of options. To help with this, follow this step-by-step checklist when guiding your evaluation and decision:

• Usability: How simple and intuitive is the documentation, SDKs, and API?
• Flexibility: Is the CMS flexible enough to meet the needs of your project?
• Uptime: Is the API/SDK resilient and does it meet your uptime requirements?
• Content editor: How intuitive is the interface for your content editors?
• Support: In what country and timezone is the vendor based, and what level of support and responsiveness do they demonstrate?
• Pricing: Is the pricing scalable and predictable for your project (will API-usage based pricing can spike up unpredictably if your website traffic increases)?

10 API-Based CMS Frameworks

New API-based CMS offerings are popping up every month, but at the time of writing, some examples include:

Wrap Up

Remember that the key benefit of an API-based CMS is they save your development team time and money. You can’t beat working with your favorite tech stack while having nearly zero maintenance.

If you’re an agency, you’re able to launch your project faster and move on to the next project. If you’re a technology startup, you can knockout your CMS requirements in a day and get back to focusing on your core product.

To maximize this, above all other factors, we recommend choosing your solution based on developer experience. Which CMS is the easiest to integrate? Which CMS has the best documentation? Which CMS has the simplest SDKs? Don’t sweat a few extra bucks here and there on subscription costs — chances are a couple days worth of your development team’s time is much more expensive than the subscription costs you are fretting over.