Digital Services Leadership Team
NPR Story API
Wed September 26, 2012
NPR API Content Permissions Control
Of all the services and platforms provided by Digital Services, the NPR Story API provides the most fundamental value to stations, allowing digital access to NPR content and to station content. The Story API is used by both NPR and stations to contribute and consume local and national news stories.
In an effort to provide stations with more control over the content they contribute to the API for broader distribution, NPR Digital Services is pleased to announce content permissions control in the NPR story API.
Content Sharing with the NPR API
An API, or Application Programming Interface, is a structured way for applications to communicate with each other. APIs are used by web sites and mobile apps to exchange data, process transactions, and share content.
NPR’s Story API is used by many stations in the network and npr.org as an interface for digital content, including stories, transcripts, images, audio, bios, and other editorial assets. NPR, Stations, and other users of the API are each identified by a unique ID called an API key. Currently content stored in the Story API’s backend repository can be retrieved by anyone with an API key.
Content pushed to the NPR Story API is predominantly consumed in 3 ways:
- Create Once, Publish Everywhere (COPE) - Stations and npr.org push content into the API and then pull the content onto other platforms, such as other station-owned web properties and mobile apps.
- Station Networks - Content is shared between multiple stations in a content network, both on web sites and mobile apps.
- National - Station content is featured on npr.org and NPR mobile apps with links back to station digital properties.
How Content Permissions Work
With the new content permissions functionality, stations can now control who is allowed to pull their content from the API.
Permissions work by allowing stations pushing content to specify whether the content is a) public to all, b) public to the NPR station network, c) public to a group of stations listed in a whitelist or d) public to everyone except for stations on a blacklist. Stations can set these permissions at the individual story level.
NPR Digital Services has created a simple web interface to allow all NPR stations to create Permission Groups. A station does not need to be using Core Publisher to create and use Permission Groups.
When first logging into this web interface, stations will see the following station-specific screen.
Clicking on Create Custom Group will bring the station editor to a new screen where stations are selected for inclusion in the group.
After selecting the desired stations, the station editor will name the group and specify whether the permission group is a whitelist or blacklist.
Stations can create as many Permission Groups as desired. When a station pushes content to the NPR Story API and does not specify a Group ID, content is treated as public to everyone pulling content from the API. Pushing content with Group ID #1 will specify that content may be pulled only by NPR and NPR member stations. Finally, using a Group ID created with this interface will mark the content as whitelisted or blacklisted for a particular list of stations. In the case of a whitelist, only stations listed in the group can pull the content from the API. In the case of a blacklist, only NPR and NPR member stations NOT listed can pull the content. Please note that in order for content to appear on NPR.org and NPR apps, NPR must be explicitly included in any whitelist created.
For stations using Core Publisher, editors can access this API Permission Group interface directly in Core Publisher. Additionally, Core Publisher allows an editor to specific a default Permission Group to be used on stories. This feature eliminates the need for a journalist to specify a Permission Group with each published story.
However, a journalist can override the default Permission Groups on the story post page if desired. The post page will show all Permission Groups created by the editor.
When to Use Permissions
The mission of public media is to reach everyone with high value journalism, and the primary goal of the NPR API is to facilitate that content sharing. We recognize that some local stories have an impact that goes beyond a single station, and we regularly recommend that digital news editors search the API for stories that are meaningful to their local audience. Naturally, the republished story includes referral links to the originating station, in recognition of the content creator. So as stated above, when no Permission Group is specified with a story, the NPR API will treat the content as public to everyone.
For stations in content networks, the NPR API is an easy way to share stories. To facilitate this kind of a network, stations can continue to push content without specifying a Permission Group, or stations may instead created a whitelist of those stations in their content network.
For stations that want to keep all content private but want to use the API as a repository for distributing content, stations can whitelist themselves and NPR only.
Again, in order for whitelisted content to appear on NPR.org and in the NPR mobile apps, NPR must be explicitly included in any whitelist created. Station stories appearing on NPR.org and the mobile apps will direct traffic back to station sites.
Getting Started with the NPR API
To use the NPR API, you must first sign the Digital Services Master Service Agreement. Please contact your Digital Services Station Relations colleague.
Your Digital Services support will also create an unique API key for your station that has access rights to both push and pull content from the API.