How I fell in love with an API-first CMS

The CMS (Content Management System) was one of the first building blocks of the content driven web. The CMS marked the move away from hardcoded HTML pages, and towards our modern web in which everyone has become a content creator. They are great for businesses because the competence of building websites and managing content could not only be split in theory, but also in practice. With a CMS, we can update our website on the fly — so there is really no justification for not using a CMS.

In the world of CMSs, we as developers are tasked to create a flexible, extensible and usable systems that not only conveys meaning to readers, but also helps content managers getting their job done. In practice, a big part of this work is displaying the content that is managed through the CMS on a multitude of platforms — from desktops and phones to TVs.

Back in the day

I remember first wanting to create a theme for Wordpress. So I went to Google, searched for tutorials and articles — and ended up with tons of walkthroughs on how to update some CSS to “theme” your Wordpress site with a custom color. Or behold, add some padding — tutorials praised this as the high arts. That wasn’t what I wanted! That wasn’t what I wanted at all!

Editing some CSS simply couldn’t be all there was to it. I wanted custom HTML and for that I wanted to get the content, and then write code that would create my custom HTML structure based on the content. I also wanted to only then add CSS to present my blog posts. Furthermore, I wanted to display all sorts of things about my posts wherever I wanted to, and not just in predefined places.

Thus I kept digging. Eventually I found a few places to get information from — and while I did speak PHP back then, I remember it being overly difficult to find all the places to get all the information from. What I was longing for was a clean documentation of: “This is how you get your data, and how it is structured”.

I felt that there should be documentation to tell me how to get the data, and how to work with it. Instead I got a bunch of interdependent references of “this class can provide …”, and that was a pain. I was waiting for that moment of clarity and understanding from which I could work my magic and make my websites sparkle ✨. But that moment never came.

In the end, I messed around a bit, barely went above changing a few colors. It was miserable work. And it made me quit developing with a CMS for some time.

Putting up with old problems

As is often the case, things started to gradually improve and I bit my way through custom themes for myBB boards (at the time the biggest Open Source forum software), a Wordpress site and quite recently a theme for the static site generator Hexo titled MeiliDu.

But the basic problem stayed the same. There was just no satisfactory documentation on how to get all the data. No one it seems was even thinking about this approach. I felt caught in one of those developer bubbles where we force pain onto each other because we think things need to be hard. While really we just hadn’t figured out a good way, yet…

The solution: going API-first

Suddenly there was an answer to all my questions. The great revelation came with the advent of the API-first CMS from Contentful. The idea was simple — they would tell me one thing, and one thing only: this is how you get your data, and how it is structured. And so my websites began to sparkle ✨

An API-first CMS is still a CMS, but one that deviates from a classic CMS like Wordpress, Drupal or Typo3 by not caring about the display of the content. Instead, an API-first CMS focuses on managing content and doing that well.

The API-first CMS works by abstracting representations of your data, defining “types” of data that can be stored and instances of data that adhere to these types.

For you to use the content managed through the API-first CMS they provide an API, typically a REST API that serves the managed content including functionality to search, filter, sort and paginate the returned content.

And on top of that API, you are free to use whatever framework, methodology and language you want. Wanna build a good ol’ PHP based website? Go for it! Single Page Applications without a backend at all? Be my guest! Static site generator like metalsmith? You betcha!

My personal favorite is a pure Frontend application based on React or Choo. For professional projects my go-to solution has been a React based application with Redux brought in for state management. On application load time, simply use the Content Delivery API to get all the data. You can just put the token for that into your frontend code.

With Contentful I like to structure my application into “pages” and “sections”, with the later being building blocks that a page can be built from. The heading of a page or a section about “four points that differentiate our business” could be such building blocks. The frontend then simply constructs a dynamic router out of the pages and their slugs (a field that I define in Contentful) using dynamic imports to load exactly the code for the sections used on any page. Add some Stylus as a CSS pre-processor (or your pre-processor of choice) and you got a great stack for a Contentful-powered website.

I’ve been having a lot of fun writing React-based applications that gather data from Contentful as an API-first CMS on load time. It has been a bliss to simply define building blocks within our websites and empower content managers through corresponding content types in the CMS.

The ease of development has astounded me, simply get all your data in a structured way (or at least the data you initially need, think about loading times) and render it on the fly. No need for backend scripts to render your site, no need to manage databases or crawl through overburdening documentation. Just focus on building great websites.

Living the dream

Now with an API-first CMS in place, all my hopes have come true and I finally have a good documentation of how my content looks as well as how to use it. All I have to do is write a frontend that will consume the REST API.

However, there are still some concerns. Let me address my two main concerns:

Cost: managed API-first CMS solutions come at a price. You can probably estimate a good 250$ per month for an API-first CMS to get started — or at least 50$/month to enable multiple users. Of course you could opt for Open Source solutions and self-host them, but chances are that you are making this move to reduce your workload. And precisely that is the strongest argument for the price. Separating the concerns of content management and content presentation will save your developers heaps of time — time that they can invest in awesome new features. Not to mention other IT staff whose time you will free up to do what really matters to the business.

Migration: chances are, you have a lot of good content. Your business uses the content for search engine optimization, to drive traffic and to educate customers. The last thing you want is to lose all that. Fear not, since API-first CMSs are content and API driven they come with great capabilities to migrate data into them. Just can define what you want to reuse, and to get an idea you can read my guide on migrating from Wordpress to Contentful.

Let me round this section off with a rundown of the benefits: API-first CMSs separates your content management from content display, thus enabling an easier understanding of what is going.

Closing Thoughts

I had a great journey along the way from the first quite clunky CMS solutions towards API-first systems. My data is flexible and unopinionated, the future is looking bright and I am glad to see my dreams about well documented content structure come true.

Originally published at www.contentful.com on May 2, 2018.