Content Distribution Service (CDS) FAQ

Below are common questions collected from Station Q&A sessions, Slack messages and emails sent to the teams that support CDS.

Differences between Story API (api.npr.org) and CDS

Launched as a public alpha release on June 30 2008, the Story API to this day serves content to many users, primarily stations with custom integrations. It also allows for publishing and sharing content to users.

What will happen to the Story API now that CDS is here?

The Story API is currently slated for retirement in early 2024 (As of the writing of this document). NPR has will continue to support the Story API has a read-only API after that retirement date. Those stations who want to publish content to NPR need to do so either through Grove for Stations or custom integrations that use CDS (Like the Wordpress plugin or Drupal module).

If you are a station or other user migrating from a service using the Story API to one that uses CDS, then this guide is catered for you.

Is there an Allow List in CDS for IP addresses similar to the one used in Story API?

No, there is not. Once you get an API key for CDS, you are all set!

Is there a full text attribute inside of CDS similar to “fullText” from the Story API?

In the Story API we had a notion of “Full Text” versus “normal text” attributes. In CDS we make no distinction between these types. Text will simply have all markup and formatting included.

For more tips like this about fields in Story API versus fields in CDS, see our comprehensive Story API to CDS field guide.

Will there be new IDs for content in CDS versus Story API?

For data that is published and consumed by Story API today, no. However, NPR may change IDs for new content further in the future. These new IDs would only be present in the CDS API.

I’m a user who has content already in CDS that made its way there through Story API ingest. Am I able to edit or delete that content now in CDS?

The short answer is: yes. If you have a CDS Key with an authorizedOrgServiceIds array that contains one or more services in a documents authorizedOrgServiceIds array, then you can edit and delete said document. For more on authentication and how that impacts your permissions in CDS, see the authorization getting started guide here.

Does the CDS have a notion of a story attribution?

Not natively like in the Story API, but the information for making your own attribution. See this guide for making your own attribution similar to Story API’s <div> element.

Story API collections versus CDS Collections

Story API had a more all-in-one approach to querying collections. If you looked up a collection for, say, Animals ID 1132, you only had to go to https://api.npr.org/query?id=1132&apiKey=mykey and you would not only see data on the collection (title, teaser, etc) but also a <list> object containing <story> elements. The story elements represented actual content inside that collection.

For CDS, we lean on using the query API to retrieve items from a collection. Fetching the collection by e.g. /v1/documents/1132 only returns information about the collection as a document and NOT anything about documents attached to that collection. While that may seem complex, it allows for the flexibility of changing a collection parent without having to change all associated children (Which was the case in the Story API).

So how do you do get items from a collection in CDS? Here’s the quick version but see our in-depth query endpoint documentation for more:

/v1/documents?collectionIds=1132&sort=publishDateTime:desc&limit=10

The above would give you the 10 most recently published stories tagged in the Animals collection.

Authentication and Access to CDS

How do I get a CDS API Key and how soon can I expect turnaround to be?

You can get an API key by contacting Member Partnership at NPR. Expect around a business week for full turnaround. You will be issued two keys per platform that plan to use CDS in:

  • One for our CDS staging environment in case you want to test out your application that uses CDS prior to production
  • One for our CDS production environment. NOTE: Only use this environment if you’re expecting the world to see your content!

Is there an expiration date for CDS API Keys?

There is no expiration date for your key. However, NPR retains the right to terminate a key after contacting you if there is a violation of our CDS API Terms of use.

Something is wrong with my key

First, before contacting Member Partnership, be sure that you have the right key and the right domain for the environment you are targeting. There are two active environments that we’ll distribute keys for:

  • Stage - https://stage-content.api.npr.org
  • Prod - https://content.api.npr.org

If you have a stage key then all calls made to CDS should be using the stage-content.api.npr.org domain. For prod keys you use content.api.npr.org.

When setting your owners and brandings array, you need to also use the stage domain for organization API:

  • Stage - https://stage-organization.api.npr.org
  • Prod - https://organization.api.npr.org

Fields, Content Types and Usage

What types of collections are going to be supported in the CDS?

The same aggregations that exist in the Story API today are available in the CDS API as well. That is because the CDS API today gets copies of the same data that Story API ingests - both systems are working in parallel.

CDS supports:

A note on “Seamus” document IDs versus modern CDS prefixed document IDs

The catch about the above statement is that you can not re-create or publish anew any Seamus-ID document. These documents have IDs that are numerical e.g. 12345 and do not have a document ID prefix. Only our NPR-internal Seamus tool was granted this ability. If you delete a document previously published by Seamus and want to republish it again, you must do so following the rules around prefixes. See the publishing guide for more.

I’m on the stage CDS environment and noticing that there’s documents missing - is there something wrong?

No, nothing wrong. Our stage CDS environment only gets updated with production data every Sunday. In addition, stage has test data that is part of our regular integration testing. So be aware that this is not a real isolated environment.

I’m getting an error when trying to publish that references a regex and my document ID - what is wrong?

Recall from Getting Started that document IDs are required to be prefixed by your own document ID prefix (e.g. abc-*) AND you need to have all lowercase alphanumeric characters.

Hosting content in CDS

Will my images, audio and other assets get “re-hosted” at NPR HQ when I send the data to CDS?

No. We will take your URLs as they come through in the various documents you send CDS and simply save that JSON to our CDS backend. Then clients will receive your documents as-is. There is not any redirecting, uploading or re-hosting of your content. Exceptions would be if, on your CMS/client end, you either use an NPR hosted URL for an asset OR you upload your content to NPR’s CDNs and then use that URL.

Table of contents

© 2024 npr