This is the first of a series of posts that will discuss decisions we made in the design, architecture, and implementation of the API. We hope that our experiences will be useful to you when working with APIs and similar software projects. We also want to hear from you--what you like, what you think should be changed--so we can make course corrections as the API evolves. So put your software geek hats on and let's talk code.

My favorite way to consume the API is using JSON. With just a few lines of code, I get a data object that I can use with JavaScript--no messy parsing of XML or the DOM necessary. The structure of this JSON data object strongly resembles the structure of the NPRML XML output document. In fact, to create the JSON output, we first generate the NPRML document, and then do some transformations to create the JSON output.

However, XML does not map to JSON seamlessly. The XML in NPRML has element nodes that contain either other element nodes or textual content. The element nodes may also have attributes. It is common practice to map element nodes to objects in JSON, with each sub-element becoming a nested object. However, we had to decide on how to treat textual content and attributes.

It makes sense to make the textual content be a property of the object that contains it, but we need a name for that property. We looked at other APIs for a standard naming convention, but there doesn't appear to be one at this time. For example, Google Data APIs puts textual content in a property named $t. The Flickr API uses a property named _content. In the NPR API, we use a property named $text.

Some APIs take a different approach, treating text nodes as string properties of the object, which means the name of the property is the element node name. Yahoo! Shopping Web Services take this approach. This makes the JSON more readable and simpler, but it doesn't work if nodes with textual content also have attributes.

We map element attributes to object properties. This approach is used by many APIs, although some (such as Yahoo! Shopping) create a specially named nested object to hold all of the attribute values. With our approach, this NPRML fragment:

<show>

    <program id="2" code="ATC">All Things Considered</program>

        <showDate>Fri, 22 Aug 2008 16:00:00 -0400</showDate>

    <segNum>12</segNum>

</show>

gets mapped to this JSON:

"show": [{

    "program": {

        "id": "2",

        "code": "ATC",

        "$text": "All Things Considered"

    },

    "showDate": {

        "$text": "Fri, 22 Aug 2008 16:00:00 -0400"

    },

    "segNum": {

        "$text": "12"

    }

}]

Note that the show property contains an array. It is possible that a story was used in multiple shows. We use arrays for properties that could have more than one value. This is done even when a given story has only one value for the property.

We are interested on hearing what you think is the best approach to JSON. Have you seen other approaches that work better? Is JSON important to you? Let us know in comments.

--Harold Neal

Shortly after the launch of the API, Harold Neal and I presented it at O'Reilly's Open Source Convention (OSCON) on July 24th. Here is a copy of that presentation (requires Adobe Acrobat). This version of the presentation has been slightly modified to reflect more current data (particularly around usage of the API) as well as some other changes that will help the presentation live as a standalone document. I have also added screen shots of the Query Generator to represent the live demo of the API that we did during the presentation.

Sharing this presentation in this forum is the first step to making our process, architecture and decisions around the API more transparent and open to our users. There will be other documents and blog posts to follow with more information. Let us know if you have specific questions about our process so we can try to address them in these future posts.

Click here to view the presentation ( (requires Adobe Acrobat)

Continue reading "OSCON Presentation on the NPR API" >

It has been almost a month since we launched our API and we are now preparing requirements for our second release. What would you most like to see in the next version? Are there specific fields or standard formats that you would like us to output? Are there topics or other ways of slicing the data that you would like represented?
- Daniel Jacobson

Whatever we now loosely know as Web 2.0 has opened up new opportunities and challenges for campaigns and media entities alike. Media outlets are attempting to navigate a new media landscape with lean budgets and an eye toward identifying new revenue streams. NPR and a group of our public media partners have responded in part (with help from a CPB grant) by creating a variety of election-related widgets that can be added to your blog or Web site. Here is a rundown on some of the gems floating around in the public media universe.

Continue reading "Public Media Serves Up Election Widgets For Bloggers" >

Yesterday, NPR announced that it will be acquiring Public Interactive (PI), a company that provides Web services to many NPR stations. (You can read the press release for full details.)

Several folks have asked me what the relationship will be between the NPR Digital Media team and the team at PI. As happens frequently in public media, our two groups have have collaborated on a number of projects over the years. For example, NPR and PI are currently partners (along with several other organizations) in a collaboration to improve online election coverage across public media. My hope is that with a closer connection between the two groups we will find many more opportunities where it's beneficial to work together.

However, while there are synergies, each group really has a distinct focus. NPR Digital Media's main mission is to create and distribute NPR content to users, stations and other partners on a variety of digital platforms like NPR.org, NPR Podcasts and NPR Mobile. Public Interactive is really focused on directly serving the digital needs of stations by providing tools and services. PI also distributes content to stations, but they work with multiple content providers including Reuters, BBC, PRI and the New York Times Syndicate (as well as NPR). We believe that it's important for PI to maintain this kind of independence to ensure that they can best meet stations' needs. To reflect these two important but distinct roles, NPR has decided that they will be managed as separate units, though there will likely also be many areas where we can collaborate.

I'm looking forward to getting to know the PI team better over the coming weeks and to see how we can work together to best serve the overall mission of public media.

What do you think about this announcement? Do you have any advice for NPR and Public Interactive as we go forward in working together?

--Darren Mauro