Although hypermedia APIs may not be a fit for every situation, they can be a powerful option when both standardization and flexibility are needed for cross-organizational data. That’s a key reason why a hypermedia API lies at the core of the Public Media Platform (PMP), a collaborative project among five of the country’s leading public media organizations.
Developed with support from the Corporation for Public Broadcasting, the PMP will be to public media’s digital content what its satellite system is for its radio and television broadcasting. The PMP will allow producers of public media to store, share and distribute a spectrum of digital content – ranging from text and audio to images and video – in a cost-effective and efficient manner.
Javaun Moradi, a member of the National Public Radio (NPR) team that led the PMP’s development, outlined the central challenge in designing the system: “The need we specifically addressed with this new PMP API is distributed publishing; you can’t assume everyone has the same publishing system because they don’t… it has to be interoperable even though everybody is different.”
In other words, there was a need for a system that could handle content from multiple publishers, combined with an ability to push that content to multiple platforms.
Moradi explained that, in the early stages of tackling this challenge, the NPR team recognized aspects of its project that needed to mirror the Web as a whole. “The Web just works,” said Moradi. “A browser can understand a few simple components, and they can be reassembled into an infinite number of possibilities.”
Following this line of thought, the team arrived at the concept of hypermedia APIs. Irakli Nadareishvili, who leads the team, describes it like this: “There are APIs that are very service- and demand-oriented, and those are usually built as RESTful APIs. And then there are APIs that are really trying to bridge data across big organizations, and I think that’s where hypermedia APIs really shine.”
In coming to that conclusion, the NPR team took a lesson from its past experiences. A central component in its legacy system – the Story API – was originally architected solely to distribute content to mobile applications and to cars. And although that framework worked well for the one-way transfer of relatively homogenous data, it was not optimized to handle expanding use cases. For example, as NPR member stations began to add their own content over time, the existing data model restricted them. If a field wasn’t already there – such as latitude and longitude coordinates associated with a story – a station couldn’t incorporate it.
Standardization and Flexibility
The PMP hypermedia API attempts to move in a different direction.
“We’ve written a very simple and extremely powerful API where we basically stripped it down to its bare essence,” said Moradi.”
The API contains some central standardization, such as search possibilities and options, but the way in which they’re implemented can be different across organizations. In addition, having flexibility in data structures also required pushing business rules to the periphery and bringing communications to the forefront.
The PMP’s target audience goes beyond those with technical knowledge, as well. “Most of our use cases were around discovery, and not just API discovery,” said Moradi. “We wanted to build something that, in a few years when this becomes more mature, can be used by a news editor – that has no idea what APIs are – to browse, discover content, and quickly get that content to where it needs to go. What we’ve built now is really good pipes.”
The core of the PMP is a new hypermedia type called Collection.Doc+JSON, based on the existing hypermedia type Collection+JSON. The new standard was registered with IANA earlier this year, and, notwithstanding its development alongside the PMP, is general enough to have uses outside of public media.
An important component of a Collection.Doc document is the embedded “profile” link, a concept borrowed from an existing standard. The power of the profile construct is that it can serve as a common framework for how data is structured while also being extensible. And, given that profiles in Collection.Doc documents are accessed solely through linking, there is also no requirement that profile descriptions be kept in a single repository – allowing for innovation to occur in a decentralized way.
To start the process, the NPR team is developing a “story profile” as a bare-bones framework that other PMP members can extend. It represents a common use case encompassing elements that most news stories have, such as a title, publication date and, potentially, an author. Other organizations will be able to add their own proprietary fields if needed, but, in all cases, the group will be able to fall back on the common structure.
In describing the story profile, Moradi pointed back to the latitude/longitude example. Imagine, he said, that over time more than one station or publisher decides to extend the profile to integrate geographic coordinates. At some point, once a number of members have determined the best practices for that type of data, the standard could be updated for everyone – a case of how flexibility and decentralization can combine to create organic innovation.
And, in the future, the process of adding entirely new use cases won’t involve the creation of new API endpoints. “This system is an API of all content types … we’ve [currently] got a Stations API, we’ve got a Transcripts API – those are just different profiles,” said Moradi. “You don’t build a new API anymore; you build different profiles.”
Lastly, for these public media organizations – whose content is their business – a successful PMP is needed to include a robust system for privacy and security. Moradi emphasized how important it was for all of the public media partners to understand that they would have full control over their own content, and that the Collection.Doc+JSON hypermedia type provides that ability.
An Approach to Sharing Data
Both Moradi and Nadareishvili noted that the concepts and the framework behind the PMP are an instantiation of something larger.
“This is the most interesting thing we’ve ever done with APIs,” said Moradi.
But, beyond that, it’s a different way of approaching data sharing among organizations.
“In my mind, hypermedia APIs are the next stage of big data,” said Nadareishvili.
He noted that even well-known and large APIs – such as those provided by Twitter and Twilio – can operate only on the content within their own databases.
“So, in that sense, it’s like an island in the universe of the Web,” he explained. “The Web is constructed in the spirit of, ‘Everybody publishes everywhere,’ and then we have ways to reach that data through hyperlinks, through Google search and other methods. APIs have not really reached that stage yet … but that’s where I think hypermedia APIs will have the biggest impact, because they’re all about linking and making connections across organizations.”
And that’s exactly what the PMP aims to do.