Inside NPR.org

API

JSON and the Argot-nauts

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:

All Things Considered
Fri, 22 Aug 2008 16:00:00 -0400
12

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.

Comments

 

Please keep your community civil. All comments must follow the NPR.org Community rules and terms of use, and will be moderated prior to posting. NPR reserves the right to use the comments we receive, in whole or in part, and to use the commenter's name and location, in any medium. See also the Terms of Use, Privacy Policy and Community FAQ.

This approach seems incredibly flexible. It's good to know how this kind of thinking fits into the way NPRML and JSON is structured. It also helps me to understand JSON better. JSON is important to people, even if they don't know how important it is to them... yet. Anyone who wants flexibility of creating and distributing widgets is likely to arrive at JSON, if only for its cross domain scripting abilities. Oh, and look... I didn't know that you all had program codes included in the architecture. See what looking closer will do. Thanks! JT

Sent by John Tynan | 4:59 PM | 9-2-2008

Inside NPR.org
Support comes from: