ButterCMS was our top public API of 2021. Here's why.

Why ButterCMS Is On A Roll With API Enthusiasts

Sizzling puns aside, Nordic APIs’ judges have officially spoken: ButterCMS API has claimed victory in our 2021 Best Public API competition. The annual event evaluates a shortlist of community and self-nominations — analyzing core facets like design, developer experience, security, and API strategy. While many APIs are worthy, only one can rise to the top. Why exactly did the ButterCMS API impress our panel?

Empowering Smarter Marketing and Content Publishing

To better understand what makes the ButterCMS API unique, we must consider primary use cases. The ButterCMS team has worked hard to design stellar content experiences through their platform. For those unfamiliar with CMSs, they’re popular conduits through which publishers (via apps or websites) can push new content to users regularly. This is critical to grabbing user attention and building a base. Blogs and other marketing-centric outlets typically rely on these mechanisms.

The ButterCMS product works similarly. You can use it to build a marketing website (or multiple), craft a blog engine, and manage multi-channel content efforts throughout a service’s lifecycle. Accordingly, ButterCMS provides solutions for eCommerce, agencies, SaaS vendors, and marketplaces. Those cases cover a wide swath of users. Professionals of varying technical acumen also lean on the solution — so it must be usable for both developers and marketers alike.

There are different ways to approach this. First, low-code/no-code options are popular because they rely on a GUI to house most critical functions. It’s easy for all users to jump in and get started. Most actions administrators could hope to take are point-and-click. Conversely, headless CMSs are gaining steam because they remove the presentation layer. This negates a lot of coding responsibilities on the development side (to satisfy various devices and OSes), and instead focuses on serving content dynamically via APIs.

ButterCMS offers a unique blend of these functionalities. The user dashboard is a major selling point for teams; it acts as a sort of centralized “command center” internally. However, the ButterCMS API powers numerous headless features of the platform. It’s a tool developers can harness as they shape their cross-platform content libraries. Since many of these functions are privilege-based, the API also includes controls for authentication and error codes. Let’s now hop into some nitty-gritty details.

What the ButterCMS API Facilitates

ButterCMS is headless, and its core API(s) are essential to delivering experiences. The headless movement is beginning to define modern, industry-wide approaches to content publishing. To better understand this, consider how today’s services work.

Microservices are immensely popular. They rely on APIs and smaller components that are decoupled — thus making applications more modular and maintainable. While a monolithic team might oversee multiple applications, modern DevOps teams find it easier to integrate APIs and really focus on sound implementations. The ButterCMS API is yet another nod to this trend — redefining how teams access data, store information, and translate that into compelling content delivery.

Naturally, the first judge of any API is what you can actually do with it. The ButterCMS API includes a host of core functions and components for content teams:

  • The Write API supports creating or updating blog posts, creating or updating pages, plus creating, updating, and deleting collection items.
  • Adding and editing components
  • Previewing page content
  • Get functionality for requesting single pages, multiple pages, and page types
  • Querying lists of search results for pages
  • Creating content relationships and hierarchies based on type or collections (reference fields)
  • Localization
  • Retrieving and filtering collections
  • String objects for authors, categories, and tags—plus feeds
  • Specialized content Webhook events and the Image API

The ButterCMS API is a REST API. It’s built around a RESTful framework and returns predictable JSON responses based on your requests. Resource-oriented URLs are standard. Finally, its baked-in libraries convert responses into language-specific objects. No post-translation or deciphering duties are shifted onto the user.

The POST portion of the API takes a programmatic approach to content production, according to ButterCMS. This supercharges content scaling. While all field keys are required, the API allows you to POST an empty string for non-essential fields. For example, your content page might not need a hero_image. You’d denote this with some variation of hero_image: "", depending on the language.

A true advantage to the ButterCMS API is its simplicity. The API doesn’t bog you down with options or configurations that leave you scratching your head. Extracting maximum value through less scripting is easy.

Notes on Documentation

ButterCMS’ documentation is thankfully easy to follow and well-organized. This is the result of the vendor’s concerted effort to improve developer reference materials. Those improvements have arrived in lockstep with Butter’s maturation.

Another check in the win column for the API is its language support. Documentation is written for developers who prefer curl, C#, Dart, Go, Java, Javascript, PHP, Python, and Ruby. A simple toggle reveals tailored instructions. This sidesteps the cluttered layouts we sometimes see within API docs. Many APIs functions have examples attached, which include informative code snippets.

You make API requests through the CLI — which is relatively straightforward without requiring too much technical knowledge. No matter which language you choose, ensure that the latest packages are installed on your machines to fully harness ButterCMS API.

There’s also something to be said for universal technologies. Language support aside, the creators of Butter have emphasized tech-stack agnosticism. Their API design makes it compatible with a staggering variety of frameworks, including:

  • Angular
  • Django
  • Express.js
  • Flutter
  • Gatsby.js
  • Laravel
  • Next.js
  • .NET

This isn’t a complete list, but it IS impressive nonetheless. ButterCMS provides full integration documentation for each of these stacks. You can also run it within Postman. This allows you to experiment with the API by testing import requests, exporting requests, adding variables, and the like. Postman also lets you leverage languages outside of Butter’s own documentation.

Some Words on ButterCMS from Jake Lumetta

We got in touch with ButterCMS Founder and CEO, Jake Lumetta, to get his take on the service. While taking the kids on a celebratory trip to Disney is on his radar, he was quick to mention the contributing factors to Butter’s success.

Accordingly, he expanded on the origins behind ButterCMS (and the API). The company was born from frustrations with other CMS tools on the market:

“ButterCMS was born out of pains trying to get WordPress to work with a modern tech stack that I experienced when leading engineering at a venture-backed startup. I founded Butter to build a modern CMS the way it should be… ButterCMS is an API-based or headless CMS. We allow you to do the same things as WordPress in terms of enabling your clients, marketing team, and non-developers to use a friendly interface to create marketing pages, write blog posts, and manage content, but we enable it in a very different way.”

API design iteration has also been central to Butter’s development:

“Keeping the endpoint design and payload response simple and clean is huge to encourage adoption. It’s kind of an obvious point, but you’d be surprised how tempting it is to return a little extra data just in case someone needs it for this one use case. Fight against that urge and keep your API as clean as possible otherwise, it becomes bloated quickly.”

Finally, Jake touched on the critical elements of API development in the CMS space. Performance and scaling have been crucial in building customer trust. It’s hard to hide performance issues, and the team has vigilantly refined the API to avoid them. Lametta shares that maintaining a strong backend infrastructure has been instrumental here. Additionally, strong caching strategies have made a world of difference.


We’ve come away quite impressed with the ButterCMS API. The project has been a labor of love — focused on favorable developer experiences, while the UI portion itself invites non-technical contributors. It’s approachable and functional, and these traits are fleeting for many other APIs on the market. The enthusiasm around the API is palpable.

Butter’s API team has made great strides following the platform’s 2014 debut, and we’re thrilled to see what they conjure up next. Companies like Salesforce, Kaplan, and Indeed (among others) already trust Butter with their content pipelines.

Want to explore ButterCMS further? Swing by the company’s GitHub page here, or follow Butter’s Twitter account.