CHAPTER 7

Making Sense of Content APIs

I’m not an API expert—and this chapter won’t make you one, either. But as you prepare content for multiple destinations, I’ve found it’s helpful to get a bit more comfortable with the technology that’s quite likely to transport it.

In this chapter, we’ll step away from our focus on the content itself for a brief discussion of APIs, or application programming interfaces: what they are, how they can make content go further, and what those of us in content strategy, IA, and related fields need to know to help make it happen.

What Is a Content API?

Imagine this: your organization or client is coming out with a new product. The information about that product will need to be added to places like:

• The products section of the main website
• A microsite built for this line of products that’s used by sales reps at trade shows
• An iOS application
• An Android application
• The product catalog
• The parent company’s website
• Major retailers’ ecommerce sites

How will all that content make it everywhere it needs to go? More and more often, the best answer is via a content API.

A content-focused API is, in many ways, the same as any other API. Just like the Google Maps API allows Google content to be used on lots of non-Google websites, a content-driven API stores data in a central place where other services can access and use it. After all, content is data, too.

There’s just one key difference. Unlike many other types of data, like the precise latitude and longitude used in Google Maps, content—with its rich descriptions, complex narratives, and conceptual ideas—can be highly ambiguous to the machines that drive APIs. Without context and human attention, its meaning is much more difficult to parse.

Which is exactly why APIs are so important for “content people” to consider—because before content can be sent out over an API, it must get into that API. So the better we are at designing the content that goes in—which then influences the shape of the API itself—the more equipped our computers will be to process it effectively and meaningfully.

API 101

Surprise, surprise: all that work you’ve already put in, analyzing content, structuring it meaningfully, and improving the way your CMS stores it? It’s that attention and care that will allow your content API to perform.

To give you a frame of reference for how a content API could be used in your organization, let’s look at some examples.

Content APIs in Practice

All sorts of organizations use content-focused APIs, and new ones are cropping up every day. Here are just a few industries and organizations that have blazed the trail toward publishing everywhere from a central API.

Major Media

Several major media organizations have been adopting APIs over the past few years, perhaps most notably in 2008, when both NPR and The New York Times announced theirs.

The Times’ first API—released in 2008, during the throes of election season—included one simple, timely, and immensely useful type of content: presidential campaign finance data. Today, the organization’s API offerings have grown to include more than a dozen types of content: movie reviews, most-popular articles, event listings, and article search, just to name a few. But that doesn’t mean all Times content is available to anyone and everyone who requests an API key. Instead, each API offers a selection of content the Times is willing to share with third-party developers—for example, for the most-popular stories, API only makes titles, metadata, and links available (see Figure 7.1). If you want the rest, well, you’ve got to go to nytimes.com for that.

FIGURE 7.1
The New York Times’ API for most popular news, one of the many APIs the organization offers that allows third parties to access and use Times content.

NPR launched its API in 2008 as well, but with a different use case in mind. Instead of wanting to open its content to third parties of all types, the organization originally wanted to get better, richer story content into the hands of its member stations, as we first learned in Chapter 2, “Building a Way Forward.” But NPR quickly learned that their API would allow them to do so much more on mobile as well. In fact, the organization credits its API as the catalyst for its tremendous growth in mobile traffic, pageviews, and readership.

Products and Shopping

It’s not just publishers that can benefit from a content-driven API. In fact, retailers have been using them to share shopping content across sites for more than a decade.

When you think about it, products are an obvious example of structured content at work: each item consists of multiple elements—like the product’s name, description, images, price, and available sizes or colors, just to name a few. That information gets organized into databases that help companies process orders and track inventory, so it’s no surprise that retailers long ago figured out how to use this structured content to publish their product content online and across multiple sites.

For example, Zappos—the online retail store known for fast free shipping and an incredible selection of shoes and other products—uses a public API to allow developers to make use of its enormous product database. The result? Zappos content is easily integrated into things like shopping result aggregators and price comparison sites.

Meanwhile, Netflix uses an API to deliver both streaming video and the content that supports it—like titles, descriptions, genres, casts, and a whole host of metadata users rely on to search and select films and shows—to a wide range of devices, from TVs to smartphones to its iPad app, as shown in Figure 7.2.

FIGURE 7.2
Netflix pushes its collection of programming content—like descriptions of movies, series, and episodes—out to multiple platforms via its API.

Government and Education

When you think about organizations managing big, messy content, you might think about government agencies and higher education institutions—large, decentralized entities with many departments creating and publishing many kinds of information, from research reports to news to forms. These organizations are also now turning to APIs to make content more portable, personalized, and flexible.

For example, FCC.gov—the website of the Federal Communications Commission—got an overhaul in late 2011, and the changes were much more than skin deep. In addition to a fresh design, the commission launched substantial new features designed to make its site, and the more than 250,000 pieces of content it holds, more searchable and accessible for a broad range of audiences—including frequent visitors, like telecommunications lawyers, and one-time visitors, like consumers filing a complaint.

How did the FCC do it? Via an API, of course. With help from Seabourne Consulting, which created a Drupal content API module for this project, the FCC launched the API in late 2011. Today, all of the organization’s content lives in one central repository within the Drupal CMS, where it can then be published to both FCC.gov and a new beta site, my.FCC.gov, which is designed for frequent users who want to create custom dashboards of content (which we’ll discuss at length in Chapter 10, “Reusable Content”).

Seabourne Consulting is also designing a new mobile site for the FCC—and guess what? It’ll run off the same API, but with content focused on timely information, like recent legislative updates or upcoming events—information they know mobile users want based on in-depth user research and site analytics. In fact, the API is even creating some unexpected benefits inside the FCC by powering a new cataloging system.

Why API?

As you can see, organizations have widely varying reasons for adopting a content-focused API. Some, like NPR and Netflix, want to increase their reach by getting content onto more and more device-specific applications and platforms. Others, like Zappos, want their products appearing across multiple shopping sites—ideally leading to increased purchases. Still others want to use an API’s structured content to power personalized content experiences, like FCC.gov. And that’s just a few examples.

For any or all of these reasons, APIs can be quite powerful. And consider this: so far, many popular APIs have been created by people who aren’t thinking about things like key messages and storytelling, or about user journeys and tasks—and who therefore aren’t prepared to improve content’s structure to support those things.

What would the possibilities be like if people like us got involved? It’s time we all find out.

API Approaches

All right, so you promise to stop fidgeting in your seat whenever the tech team starts talking in acronyms? Great. Then there are a few more things you need to know about how APIs can be designed and configured to handle content.

Public Versus Private

When public media sends content out over the API, it increases its reach. The more people who listen or read, the better for NPR. But that isn’t the case for many organizations, which want to limit their content to properties they own.

You needn’t be opening your content up to the world for an API to make sense. If you want to retain some control over publishing but still want content that travels, a private API may be a much better fit for your content’s future. Unlike public APIs, which developers from third parties can access and use according to the API’s specifications, a private API’s use is limited to those within an organization—as Netflix uses theirs—or perhaps within a limited network of partners.

In fact, many organizations have multiple APIs, some internal and some external. For example, NPR offers different APIs to different groups: a private API for those within NPR, who get the greatest flexibility in what content they can pull from the API and how they can use it; another for member stations, who receive some flexibility in terms of content and use; and a public API for external third parties like NPR Addict, which are the most limited in what content they can receive from the API. These limitations include editorial considerations—what NPR wants external parties to use—as well as legal ones, such as photo usage rights. And because the API includes rich metadata about all the content NPR produces, it’s easy to filter out which content may go to whom, and when.

Read Versus Write

You’ve got content and you need to get it out there, like, right now. So why should your API need to also accept inputs from others? Even if your primary purpose is to publish your content to the world now, the ability to allow others to write content—that is, to upload their stuff into your API—could soon be a huge boon for your business or organization.

As the number of organizations making content available via API increase, the opportunities for you to enhance and enrich your content with information from other sources—sources with content that your organization could never create or manage itself—increase as well. If your API can accept others’ content, you’ll be better able to create cohesive content experiences—experiences that mash the content you’re really, really good at creating with the complementary stuff you’d never be able to pull off...but that your audiences want and appreciate.

Bam. Added value all around.

What About RSS?

You may be thinking that all this talk about sending content across multiple sites sounds a lot like RSS. You’re not wrong. An RSS feed is basically a simplistic API. After all, RSS stands for real simple syndication, and its capabilities are limited.

RSS simply makes a feed of content available to external machines, like the 10 most recent news items, for example. You set the parameters when you establish the RSS feed, and that’s what the other side can receive.

An API, on the other hand, is more like a conversation between two machines: one machine makes content available. The other asks for the specific components it wants, and the first one provides them. With an API, you can slice content in different combinations, allow users to search for content, and a whole host of other things—as well as the things that RSS can do.

Scoot Up to the API Table

When NPR launched its API back in 2008, it admits that things were imperfect: some features never caught on; some common story types weren’t supported well. As the organization has revamped and improved its API over the years, it’s addressed these weaknesses by making the editorial team more invested in API decisions—rather than just the engineers.

If your organization is considering or enhancing an API, there’s a lesson here. When the people who know the content best are included in talks about how that content will be structured, stored, and transported, things just work better. Which means, if you’ve taken the time to break your content down and understand its inner workings, you’re the perfect person to advocate for APIs that respect your content and your content creators’ capabilities and constraints.

Understanding the role of the API in content distribution can also help you educate those content creators, showing them how to adjust their thinking and their workflows to be more efficient—and still create great content—in the future.

Finally, because you should be pretty much in tune with your audiences and your organization’s goals by now, you’ll also be prepared to help the team make decisions about what content should be available to whom, as well as how that content might need to change when the API sends it to different products, devices, or channels.

Putting It All Together

Not everyone will need an API, true. But they’re getting more difficult to avoid. Today, you may just need to publish across desktops, tablets, and smartphones, and you may find that a responsive website design does the trick just fine. But soon—if not already—you’ll face even more connected devices: Internet-enabled televisions, cars, refrigerators, and thermostats, just to name a few. While responsive design can work wonders, it’s not going to work for all these varied display sizes and contexts.

Instead, many organizations—media, retailers, government agencies, or any of the countless spaces in between—will need a way to transmit content that’s normalized and separated from display. The better informed you are now, and the more effectively your content is structured, the more likely you are to be included in those conversations in the future.

But never forget: you can’t send content out over your API unless you have good content going into your API. Which means getting content everywhere you want it still comes back to the people creating and entering it in the first place, and their ability to stop thinking about fixed pages and start thinking about building more flexible content systems—in other words, the stuff we’ve been working on throughout this book.

You’ve got the theory down. You’ve broken free of the page and started thinking about your content’s microstructures, systems, relationships, and priorities—and you’re comfortable talking about the metadata, markup, and APIs that might support them. Now it’s time to embrace all the incredible places your content can go with this thinking in place.

In Part III, “Putting Structured Content to Work,” we’ll go from approach to application by exploring how this more flexible mindset is helping organizations of all sorts create content that’s more findable, adaptable, reusable, and transportable—and how you can do the same.