Cleve Gibbon

content management, content modelling, digital ecosystems, technology evangelist.

Content APIs: A is for Access

Please watch this two minute video. It does an amazing job of describing the utility of APIs using a deck of playing cards.

Content APIs are on the rise because we need ubiquitous access to content.  For a while now, I’ve felt like our content management systems are being deployed as Roach Motels (see resources at the end), where content checks in, but it doesn’t check out. Forever locked into a single (web) channel with no easy way out.

A couple weeks backs, I explained why content APIs are becoming critical to those in the content business.  They help mitigate the Roach Motel problem.  The big guns are already reaping the rewards of their early investments in content APIs. Take Netflix, after just two years of deploying an API, it’s seeing a x37 increase in API usage, the majority of which is through internal consumption.

Today, let’s walkthrough through a couple of examples to drive home the point that APIs lower the bar to making content accessible: available to people, processes and products that potentially do not to contribute to the production or ongoing management of the content.

Multi-Device Application Design

Luke Wroblewski of Mobile First recently published a video series for Intel for Re-Imagining Apps for Ultrabook.  In Part 6 Luke talks about cross device usage, highlighting that we need to re-think our standard desktop application designs to cater for multi-device experiences.  Luke goes on to break cross device usage into four categories; stating that access, flow, push, and control must be considered when designing applications that need to span multiple devices. So, what is access?

Put simply, access is (the) ability to view or interact with the same content or features across more than one device. (Luke W.)

A content API is a service that provides consumers with ubiquitous access to content.  In the case of multi-device application design, a content API gives application designers and developers, on their target device platform, access to the same content.   It’s all about access.

Access, access, access. Without a standard way to get to the content, there will be multiple workarounds, teams, budgets and tactical solutions to achieve the same goal.  We’ve all seen it.  Go direct to the CMS, or export as XML, or expose as RSS/Atom feeds, or dump content into another database, or screen scrap HTML site pages, or pour content into spreadsheets, and so on.  It’s expensive, uncompetitive and stupid.  Content APIs are a strategic answer, not a silver bullet, to facilitating a standard and controlled access to content.

Learning to COPE

I’m a keen subscriber to the Insert Content Here content strategy podcast series by Jeff Eaton over at Lullabot.  In Episode 11, Daniel Jacobsen talks about his time at NPR working on Create Once, Publish Everywhere (COPE) and Content APIs.  Here are the four philosophies that underpinned and shaped COPE:

  1. Manage content. Content Management Systems are for managing content, not web publishing.
  2. Raw Content.  Separate content from display; rendering display-agnostic content is a channel-based, target delivery system (device) concern.
  3. Modular Content. The ability to assemble and disassemble content to create new kinds of content.  Although Daniel spoke more to the modular “storage” of content within a database, not all content is stored in a database, but the same principle of treating content as lego building blocks still holds.
  4. Portable Content. Content portability is about preparing and getting content everywhere it needs to be.  Having a content API helps but alone it is not enough.  Can the target platforms consume content delivered via the API?  How do we deal with text emphasis?  What editorial challenges do we face with modular content that can be re-assemble in multiple, unforeseen ways?

Content APIs gave NPR flexible and accessible content that embraced COPE.  Daniel moved on and joined Netflix, and then 18 months later, Zach Brand on taking over the NPR API tells us what they did wrong.  Although the improvements resulted in a 22% increase in API response times, he left this warning…

…so while the API supports nimble change of our other products, making changes to the API itself was rather difficult.

API Design

So what is Zach really telling us.  He’s telling us what we already know deep down: designing APIs is hard.  And damned straight they’re hard if we expect them to scale, evolve, whilst always being available.  There’s a ton of things to consider, but this is what we know:

  • A content model defines the important content types and their structure.
  • A content API  enforces how and what content is accessible to its consumers.
  • The API provides a clear separation of concerns between those producing content and those consuming it.
  • Most Web based APIs tend to be based upon REST, a technical solution that enables someone to access web resources over HTTP, where for content APIs those resources are your content.

Daniel, highlighted a few concerns with RESTful APIs that his team at Netflix encountered.  He found that for the multi-device world Netflix pre-dominantly operates in, REST proved to be too generic in it’s approach.  They found that their one-size fits all…

…REST API, while very capable of handling the requests from our devices in a generic way, is optimized for none of them. (Daniel J)

Netflix are re-visiting their API designs because APIs need to evolve, not only to scale but to meet ever-changing business needs.   These moving goalposts highlight that API designs need to be flexible, and it’s important to strike the right balance between delivering value today and preparing for inevitable change tomorrow.

Who designs and develops APIs?

Every developer has written an API.  We love them, but be vigilant. For every one great API, they are hundreds, if not thousands of bad ones.  Taking the developer skill level out of the equation for now, API writing tends to be tactical.  You’re a developer, in the weeds, at the sharp end of a specific project or problem, and design and develop an API within that context.  The same thing happens in adjacent developments in similar projects across the business.  Before you know it, we have multiple APIs solving the same problem, but slightly different to cater for the target context.  It’s the nature of the beast.  We tend to design and develop multiple APIs in silo’s.

In order to stop writing one-off tactical APIs and start leveraging the distribution of scale, we need to design for strategic APIs.  That’s a much bigger deal, requiring vision, strategy, senior buy-in where the API is positioned as a business asset not just a technical project assist.  Strategic APIs require small teams of developers that focus on building value into making content and features accessible to the masses.  Daniel Jacobsen talks at great length about this real value in his book on APIs: A Strategy Guide.


Although API design is hard, companies are succeeding.  Guaranteed they failed first, and a continuing to fail fast, but adapting as they go.  You’re development teams are already writing (tactical) APIs, trust me.  However, the real value comes from consolidating all those tactical efforts around a strategic goal to make content accessible.  That’s what takes the time, but once sorted, you have all the technology required to get your content everywhere.


The Roach Motel. I stumbled upon this advert when I toured America as student. I’ve never been able to fully shake off the strapline line; roaches check in but they don’t check out.

Joshua Bloch.  A well-known Java developer and evangelist that implemented a number of the APIs within the Java language itself.  This is a talk aimed at developers he gave at Google on how to design great APIs. The basic principles, a decade on, still hold up.

Category: content architecture, content modelling


Leave a Reply

About Cleve Gibbon

I'm a technologist passionate about enabling consumers, employees, and clients do more with less, whilst having fun at the same time.

My sort of up-to-date cv tells you my past, linked in shows you my professional network and on twitter you can find out what I'm currently doing.