This post first appeared on ProgrammableWeb.com

As discussed in my previous post, COPE (Create Once, Publish Everywhere) is a fundamental philosophy that drives NPR’s digital publishing and distribution strategy and is the foundation of the NPR API. Supporting it all is a single system that manages all incoming content and funnels it out through a single distribution pipe, regardless of content type or destination. A key principle that supports COPE is ensuring that content is stored in a modular way.

Modular storage of content is more than just database normalization. It requires strategic design of the data model to ensure that discreet objects are stored in distinct locations. To create the right design, you must truly understand your system and the assets that it stores. That is, you need to be able to identify and represent the object (or series of objects) that is at the core of your system. For NPR, the core of the system is a story. We then attach “resources” to the story, each of which is its own object in the database (examples of resources include full text with each paragraph stored as distinct records, audio, video, images, related links, and a range of other object types). Then stories get attached to lists, which are essentially a series of taxonomies that help our systems slice through the stories.

The diagram above is a basic entity diagram of how NPR manages data for a story, some related resources and the list to which the stories are assigned. This is a conceptual model that represents how these entities relate to each other and does not include all resource or list entities in the system. The physical model, obviously, is much more complex. Click here for a larger and more complete view of this diagram (PDF).

NPR’s system is obviously much more complicated than this, but the breakdown of story/resources/lists is the foundation of it all. Accordingly, storage of this information in the database needs to ensure that all of these objects can be manipulated independently. With this approach, NPR is able to create a list of all images in the system, or all stories that have video, or all stories in the News topic, or any number of other combinations of stories or resources. The power of this modularity is that we have tremendous control over what gets distributed to each destination. And the distribution of content for all of these scenarios is the same simple REST-based API, requiring no special coding to generate the content for the different destinations.

The above is an excerpt of XML outputted from the NPR API. Clean, effective storage of the content makes it a simpler and more flexible process to manage it differently as it gets distributed to different destinations. Click here to see an expanded view of the XML with annotation detailing how it maps to the entity diagram.

Conversely, WPT’s tend to store objects to enable the building of a web page. As a result, the content may be bundled together in database fields, storing the actual references to images, video and audio entirely within the story content text. It is still possible that the WPT’s are adhering to some form of data normalization in their storage techniques, but that does not mean that these systems are embracing COPE.

There are two significant problems with the WPT approach of data storage. First, as an example, the image references within the block of text will contain HTML and possibly other markup, making the text block dirty. Any distribution to other platforms could then require special treatment to prepare the content for that destination. More importantly, however, is the fact that these same images are very difficult to repurpose because they are embedded in text. So, it would be quite a challenge to make a feed of images, to identify only those posts that contain images, to resize some or all images in the system, or to consistently restrict distribution of images that do not have the rights cleared.

Building systems that manage the content in a modular way and separates it from display sets it up well to be distributed on a range of platforms. The final piece to the puzzle, however, is content portability. Content portability ensures that the content can actually live and thrive in all platforms to which it gets distributed (even those that do not yet exist). Building a distribution channel, like an API, is simply not enough anymore. Content portability must be applied at the CMS level, which will be the topic of my next article.

This post first appeared on ProgrammableWeb.com.

The digital media world is in the process of dramatic change. For years, the Internet has been about web sites and browser-based experiences, and the systems that drove those sites generally matched those experiences. But now, the portable world is upon us and it is formidable. With the growing need and ability to be portable comes tremendous opportunity for content providers. But it also requires substantial changes to their thinking and their systems. It requires distribution platforms, API’s and other ways to get the content to where it needs to be. But having an API is not enough. In order for content providers to take full advantage of these new platforms, they will need to, first and foremost, embrace one simple philosophy: COPE (Create Once, Publish Everywhere).

The diagram above represents NPR’s content management pipeline and how it embraces these COPE principles. The basic principle is to have content producers and ingestion scripts funnel content into a single system (or series of closely tied systems). Once there, the distribution of all content can be handled identically, regardless of content type or its destinations

COPE
Through COPE, our systems have enabled incredible growth despite having a small staff and limited resources. Although the CMS is home-grown, COPE itself is agnostic as to the build or buy/integrate decision. Any system that adheres to these principles, whether it is a COTS product, home-grown, or anything in between, will see the benefits of content modularity and portability.

In this series of posts, I will be discussing these philosophies, as well as how NPR applied them and how we were able to do so much with so little (including our NPR API).

COPE is really a combination of several other closely related sub-philosophies, including:

Build content management systems (CMS), not web publishing tools (WPT)

• Separate content from display
• Ensure content modularity
• Ensure content portability

These philosophies have a direct impact on API and distribution strategies as well. Creating an API on top of a COPE-less system will distribute the content, but there is still no guarantee that the content can actually live on any platform. COPE is dependent on these other philosophies to ensure that the content is truly portable.

Build CMS, not WPT
COPE is the key difference between content management systems and web publishing tools, although these terms are often used interchangeably in our industry. The goal of any CMS should be to gather enough information to present the content on any platform, in any presentation, at any time. WPT’s capture content with the primary purpose of publishing web pages. As a result, they tend to manage the content in ways focused on delivering it to the web. Plug-ins are often available for distribution to other platforms, but applying tools on top of the native functions to manipulate the content for alternate destinations makes the system inherently unscalable. That is, for each new platform, WPT’s will need a new plug-in to tailor the presentation markup to that platform. CMS’s, on the other hand, store the content cleanly, enabling the presentation layers to worry about how to display the content not on how to transform the markup embedded within it.

True CMS’s are really just content capturing tools that are completely agnostic as to how or where the content will be viewed, whether it is a web page, mobile app, TV or radio display, etc. Additionally, platforms that don’t yet exist are able to be served by a true CMS in ways that WPT’s may not be able to (even with plug-ins). By applying COPE, NPR was able to quickly jump on advancements throughout the years like RSS, Podcasts, API’s and mobile platforms with relative ease. As an example, the public API took only about two developer months to create, and most of that time was spent on user and rights management.

This presentation shows the same NPR story displayed in a wide range of platforms. The content, through the principles of COPE, is pushed out to all of these destinations through the NPR API. Each destination, meanwhile, uses the appropriate content for that presentation layer.

Separate Content from Display
Separating content from display is one of the key concepts supporting COPE. In the most basic form, this means that the presentation layer needs to be a series of templates that know how to pull in the content from the repository. This enables the presentation layer to care about how the content will look while the content can be display-agnostic, allowing it to appear on a web site, a mobile device, etc.

But to truly separate content from display, the content repository needs to also avoid storing “dirty” content. Dirty content is content that contains any presentation layer information embedded in it, including HTML, XML, character encodings, microformats, and any other markup or rich formatting information. This separation is achieved by the two other principles, content modularity and content portability

At a high level, many systems and organizations are applying the basics of COPE. They are able to distribute content to different platforms, separate content from display, etc. But to take some of these systems to the next level, enabling them to scale and adapt to our changing landscape, they will need to focus more on content modularity and portability. In my next post, I will go into more detail about NPR’s approach to content modularity and why our approach is more than just data normalization.

This post originally appeared on the Netflix Tech Blog on July 9, 2012.

As I discussed in my recent blog post on ProgrammableWeb.com, Netflix has found substantial limitations in the traditional one-size-fits-all (OSFA) REST API approach. As a result, we have moved to a new, fully customizable API. The basis for our decision is that Netflix’s streaming service is available on more than 800 different device types, almost all of which receive their content from our private APIs. In our experience, we have realized that supporting these myriad device types with an OSFA API, while successful, is not optimal for the API team, the UI teams or Netflix streaming customers. And given that the key audiences for the API are a small group of known developers to which the API team is very close (i.e., mostly internal Netflix UI development teams), we have evolved our API into a platform for API development. Supporting this platform are a few key philosophies, each of which is instrumental in the design of our new system. These philosophies are as follows:

• Embrace the Differences of the Devices
• Separate Content Gathering from Content Formatting/Delivery
• Redefine the Border Between “Client” and “Server”
• Distribute Innovation

I will go into more detail below about each of these, including our implementation and what the benefits (and potential detriments) are of this approach. However, each philosophy reflects our top-level goal: to provide whatever is best for the Netflix customer. If we can improve the interaction between the API and our UIs, we have a better chance of making more of our customers happier.

Now, the philosophies…

Embrace the Differences of the Devices

The key driver for this redesigned API is the fact that there are a range of differences across the 800+ device types that we support. Most APIs (including the REST API that Netflix has been using since 2008) treat these devices the same, in a generic way, to make the server-side implementations more efficient. And there is good reason for this approach. Providing an OSFA API allows the API team to maintain a solid contract with a wide range of API consumers because the API team is setting the rules for everyone to follow.

While effective, the problem with the OSFA approach is that its emphasis is to make it convenient for the API provider, not the API consumer. Accordingly, OSFA is ignoring the differences of these devices; the differences that allow us to more optimally take advantage of the rich features offered on each. To give you an idea of these differences, devices may differ on:

• Memory capacity or processing power, potentially modifying how much content it can manage at a given time
• Requirements for distinct markup formats and broader device proliferation increases the likelihood of this
• Document models, some devices may perform better with flatter models, others with more hierarchical
• Screen real estate which may impact the content elements that are needed
• Document delivery, some performing better with bits streamed across HTTP rather than delivered as a complete document
• User interactions, which could influence the metadata fields, delivery method, interaction model, etc.

Our new model is designed to cut against the OSFA paradigm and embrace the differences across devices while supporting those differences equally. To achieve this, our API development platform allows each UI team to create customized endpoints. So the request/response model can be optimized for each team’s UIs to account for unique or divergent device requirements. To support the variability in our request/response model, we need a different kind of architecture, which takes us to the next philosophy…

Separate Content Gathering from Content Formatting/Delivery

In many OSFA implementations, the API is the engine that retrieves the content from the source(s), prepares that payload, and then ultimately delivers it. Historically, this implementation is also how the Netflix REST API has operated, which is loosely represented by the following image:

The above diagram shows a rainbow of colors roughly representing some of the different requests needed for the PS3, as an example, to start the Netflix experience. Other UIs will have a similar set of interactions against the OSFA REST API given that they are all required by the API to adhere to roughly the same set of rules. Inside the REST API is the engine that performs the gathering, preparation and delivery of the content (indifferent to which UI made the request).

Our new API has departed from the OSFA API model towards one that enables fine-grained customizations without compromising overall system manageability. To achieve this model, our new architecture clearly separates the operations of content gathering from content formatting and delivery. The following diagram represents this modified architecture:

In this new model, the UIs make a single request to a custom endpoint that is designed to specifically handle that request. Behind the endpoint is a handler that parses the request and calls the Java API, which gathers the content by calling back to a range of dependent services. We will discuss in later posts how we do this, particularly in how we parse the requests, trigger calls to dependencies, handle concurrency, support fallbacks, as well as other techniques we use to ensure optimized and accurate gathering of the content. For now, though, I will just say that the content gathering from the Java API is generic and independent of destination, just like the OSFA approach.

After the content has been gathered, however, it is handed off to the formatting and delivery engines which sit on top of the Java API on the server. The diagram represents this layer by showing an array of different devices resting on top of the Java API, each of which corresponds to the custom endpoints for a given UI and/or set of devices. The custom endpoints, as mentioned earlier, support optimized request/response handling for that device, which takes us to the next philosophy…

Redefine the Border Between “Client” and “Server”

The traditional definition of “client code” is all code that lives on a given device or UI. “Server code” is typically defined as the code that resides on the server. The divide between the two is the network border. This is often the case for REST APIs and that border is where the contract between the API provider and API consumer is engaged, as was the case for Netflix’s REST API, as shown below:

In our new approach, we are pushing this border back to the server, and with it goes a substantial portion of the UI-specific content processing. All of the code on the device is still considered client code, but some client code now resides on the server. In essence, the client code on the device makes a network call back to a dedicated client adapter that resides on the server behind the custom endpoint. Once back on the server, the adapter (currently written in Groovy) explodes that request out to a series of server-side calls that get the corresponding content (in some cases, roughly the same rainbow of requests that would be handled across HTTP in our old REST API). At that point, the Java APIs perform their content gathering functions and deliver the requested content back to the adapter. Once the adapter has some or all of its content, the adapter processes it for delivery, which includes pruning out unwanted fields, error handling and retries, formatting the response, and delivering the document header and body. All of this processing is custom to the specific UI. This new definition of client/server is represented in the following diagram:

There are two major aspects to this change. First, it allows for more efficient interactions between the device and the server since most calls that otherwise would be going across the network can be handled on the server. Of course, network calls are the most expensive part of the transaction, so reducing the number of network requests improves performance, in some cases by several seconds. The second key component leads us to the final (and perhaps most important) philosophy to this approach, which is the distribution of the work for building out the optimized adapters.

Distribute Innovation

One expected critique with this approach is that as we add more devices and build more UIs for A/B and multivariate tests, there will undoubtedly be myriad adapters needed to support all of these distinct request profiles. How can we innovate rapidly and support such a diverse (and growing) set of interactions? It is critical for us to support the custom adapters, but it is equally important for us to maintain a high rate of innovation across these UIs and devices.

As described above, pushing some of the client code back to the servers and providing custom endpoints gives us the opportunity to distribute the API development to the UI teams. We are able to do this because the consumers of this private API are the Netflix UI and device teams. Given that the UI teams can create and modify their own adapter code (potentially without any intervention or involvement from the API team), they can be much more nimble in their development. In other words, as long as the content is available in the Java API, the UI teams can change the code that lives on the device to support the user experience and at the same time change the adapter code to deliver the payload needed for that experience. They are no longer bound by server teams dictating the rules and/or being a bottleneck for their development. API innovation is now in the hands of the UI teams! Moreover, because these adapters are isolated from each other, this approach also diminishes the risk of harming other device implementations with tactical changes in their device-specific APIs.

Of course, one drawback to this is that UI teams are often more skilled in technologies like HTML5, CSS3, JavaScript, etc. In this system, they now need to learn server-side technologies and techniques. So far, however, this has been a relatively small issue, especially since our engineering culture is to hire very strong, senior-level engineers who are adaptable, curious and passionate about learning and implementing these kinds of solutions. Another concern is that because the UI teams are implementing server-side adapters, they have the potential to bring down the servers through infinite loops or other processes that are resource intensive. To offset this, we are working on scrubbing engines that will hopefully minimize the likelihood of such mistakes. That said, in the OSFA world, code on the device can just as easily DDOS the server, it is just potentially a bigger problem if it runs on the server.

Example of how this new system works:

1. A device, such as the PS3, makes a single request across the network to load the home screen (This code is written and supported by the PS3 UI team.
2. A Groovy adapter receives and parses the PS3 request (PS3 UI team)
3. The adapter explodes that one request into many requests that call the Java API to (PS3 UI team)
4. Each Java API calls back to a dependent service, concurrently when appropriate, to gather the content needed for that sub-request (API team)
5. In the Java API, if a dependent service unavailable or returns a 4xx or 5xx, the Java API returns a fallback and/or an error code to the adapter (API team)
6. Successful Java API transactions then return the content back to the adapter when each thread has completed (API team)
7. The adapter can handle the responses from each thread progressively or all together, depending on how the UI team wants to handle it (PS3 UI team)
8. The adapter then manipulates the content, retrieves the wanted (and prunes out the unwanted) elements, handle errors, etc. (PS3 UI team)
9. The adapter formats the response in preparation for delivery back across the network to the PS3, which includes everything needed for the PS3 home screen in the single payload (PS3 UI team)
10. The adapter finally handles the delivery of the payload across the network (PS3 UI team)
11. The device will then parse this optimized response and populate the UI (PS3 UI team)

We are still in the early stages of this new system. Some of our devices have fully migrated over to it, others are split between it and the REST API, and others are just getting their feet wet. In upcoming posts, we will share more about the deeper technical aspects of the system, including the way we handle concurrency, how we manage the adapters, the interaction between the adapters and the Java API, our Groovy implementation, error handling, etc. We will also continue to share the evolution of this system as we learn more about it.

Below are the slides from my presentation to the engineering team at PayPal. This presentation discusses the history and future of the Netflix API. It also goes into API design principles as well as concepts behind system scalability and resiliency.

This article originally posted by Scott Fulton on ReadWriteWeb on February 3, 2012 as Part II in a series. Part I can be found here.

What we today call the “mobile app” could, in a very short period of time, become known as the portable app, or just the “app.” It tends to use such a simple and straightforward model of interaction that people are starting to prefer using their smartphones for certain tasks, even when their PCs are right in front of them. By this time next year, portable apps originally designed for use on smartphones and tablets may be running on laptops.

The extent to which this changes everything is a topic that no one, not even ReadWriteWeb, has fully fathomed. The Web as we have come to know it will be affected significantly. What users have come to know as Web sites will be willingly and eagerly substituted with Web apps. In Part 2 of our interview with the co-author of APIs: A Strategy Guide, Netflix lead API engineer Daniel Jacobson tells us the one huge difference between an app and a site involves the extent to which they rely on an API. It is part of every app’s DNA.

The First, Painful Steps Toward Multi-Platform

In 2002, as you learned from part 1 of our RWW interview last week, when Jacobson was with NPR, he helped make a critical decision about its information infrastructure, the implications of which his team had not foreseen: “Literally the first thing that we did,” he tells RWW, “is, we built the API and we put the Web site on top of it. So the Web site runs off the API. It’s a little bit of a different interaction model; it doesn’t have to go through the authentication and whatever else, in the same way that external apps do.”

That API later gave NPR the freedom to build apps that run outside the browser, and that use that same API in different ways. So when mobile apps were invented, NPR was among the first publishers to be ready for them. When Netflix saw it needed an architecture that enabled it to reach all its users without it being dependent upon the usage model for any one device, including the Web browser, it hired Jacobson to build it.

A 2005 Netflix demo at a Microsoft convention featured one of that company’s program managers at the time, Darryn Dieken, showing then-President Jim Allchin the prospects of using one underlying technology as the foundation for developing a unified product line across different devices. The technology at the time was code-named “Avalon,” and evolved into what we now call Silverlight.

After showing how a Netflix product selector ran outside the browser but through the Web, in a way people had never seen before at that time, Dieken showed essentially the same selector running inside Windows Vista on a tablet PC. From there, he proceeded to show where else folks would eventually find Netflix.

The demo took the audience inside Windows Media Center, which had just been released for Windows XP and was being vastly updated for Vista. The Media Center plug-in used many of the same presentation techniques and concepts as the stand-alone version, demonstrating the benefits of code reuse.

But when the demo turned its attention to Netflix on a Windows Mobile phone, it became painfully obvious that the benefits of client-side code reuse could only go so far. Yes, there was communication taking place between all these different clients and the server. But the way these interactions were happening were based on leveraging Web site-oriented, forms-based submissions that at one level could be described as an API, but failed to be uniform – one API for many platforms.

The goal of any modern API, Dan Jacobson emphasizes, is “to treat any presentation layer the same. So if you have multiple Web sites, like NPR does (they have NPR Music as well as NPR.org), both of those sites run off of the same interaction model through the API. They’re just presentation layers, the same way as mobile app or Google TV or [NPR] Infinite Radio. Users are going to consume new material in any way that they want to, wherever, whenever; and your goal as publisher is to make sure that you have a presentation layer that serves them wherever that is. And in doing so, the easiest way, the most effective way to date is to leverage APIs, and invest a little bit on having the right talent surrounding it.”

“Publish Everywhere” Doesn’t Have to Be Homogenous

Because presentation layers are so different from one another, he goes on, a business can and should nurture teams of developers with the exclusive skillsets that each of those layers needs – for example, Objective-C developers for iPhone apps. There’s no reason why certain teams can’t specialize. Having a single API that addresses each layer in a standard way, he says, provides all your teams with the flexibility they require to take advantage of the platforms on which they’re focused.

This allowance for specialization tends to work itself away from the “one Web” way of thinking, the belief that everything will inevitably merge into HTML5. In professing that API design should not be centered around any one single mode of presentation, lest it eventually become obsolete (among other reasons), Jacobson advises that API designers focus on finding ways to symbolize and encode business interactions, the things that businesses do, not the things that Web sites do. Your goal is not to make the browser more efficient or the user experience more immersive. Leave that to the UX designers. As the API engineer, your goal is to enable business.

“That kind of thinking is fundamentally different than, ‘How do I want to structure my content? Do I need to think about what resources can be broken up in which ways and made available in different ways?’” says Jacobson. “For NPR, for example, there are stories, there are assets, different kinds of things in that system. For Netflix, there are users, catalog items. How do you want to structure that material, both in terms of the resource level as well as items underneath it? What are the rights management concerns that go into this, legal constraints internally about what can be published? For Netflix, what can I show users in Latin America that I can’t show to people in Canada? For NPR, it’s, I’m publishing AP photos; whom can’t I present that to, and whom can I? Those kinds of things are really business-oriented decisions that you can’t just flip a switch and say, ‘Make it happen.’ You need to be very thoughtful about what you’re exposing and to whom, and how you’re going to do it so you can get the maximum effectiveness out of it.”

It is this concept which may outmode, or render obsolete, the traditional notion of the Web site, the notion that something that’s created once and published everywhere (COPE) must always be the same thing. Done properly, Jacobson says, it can and should be integrated with the uniqueness of each device.

“When Web APIs started out, they tended to be more about publishing on all kinds of different platforms. Now I think it’s very much about aggregation, and merging others’ API experiences,” says the Netflix engineer. “One of the interesting things with Netflix, for example: We have branded apps on a wide range of platforms, and if you look at something like AppleTV or Roku or Xbox, or any of these other devices, we’re not the only ones there. There is an aggregation of services where Netflix creates an experience on that platform. We actually integrate with their systems, we’re creating an experience on that site, and then people can access our experience in the way they expect it to be presented.”