Richie News Feed Structure

The Richie mobile applications for iOS and Android fetch content from Richie’s distribution servers in the native Richie news feed format described here. In most cases, it’s best to use this same feed format when serving content from your CMS or web site to Richie.

If serving content in the Richie news feed format is not possible, the Richie infrastructure is also able to ingest a variety of other feed formats, like RSS.

Content Structure in Richie Applications

Richie applications display news sections in a tabbed user interface using top tabs arranged from left to right. Additionally, these top tabs can be grouped into bottom tabs. Each bottom tab can contain one or several top tabs.

Richie will configure the main news sections which will be displayed in the app's main navigation. Additional news sections may be opened from the elements in those main news sections. For example, author element in each article might link to a section where all news articles of that author are listed.

Within a section, stories are displayed in the original feed order, and not rearranged by the client application.

Richie news feed specification consists of two types of feeds: section feeds and article feeds. Section feeds provide the data needed to render section front views. Article feeds provide the data needed to render article views.

Articles with external content

Richie applications support two types of articles:

• Articles that provide their HTML data, assets and photos from an Article Feed endpoint
• Articles that have an external HTTP URL which is loaded in either in-app webview or in a web browser

For articles with external content, article feed endpoint is not required, and all the required properties for these articles come from the section feed.

Section Feeds

A section feed contains all the data that's required to render a single news section in the app, and a reference to an endpoint which will be used to fetch article's content. Each section will be fetched from its own feed.

Properties are documented in the Section Feeds section.

Article Feeds

An article feed contains all the data that's required to render a single news article in the app.

Properties are documented in the Article Feeds section.

Practical Considerations

The Base URL and authorization method of section and article feeds should be delivered to Richie as part of the feed setup.

The recommended authorization methods include:

• HTTP Basic Auth
• Shared secret/token as GET parameter
• Shared secret/token as HTTP header

A sample feed endpoint structure could look like this:

• Base URL for section feeds: https://www.example.com/feeds/section/$sectionURL
• Base URL for article feeds: https://www.example.com/feeds/article/$publisherID
• Authorization configuration: HTTP Basic Auth

In the sample case, section feeds would be fetched from URLs like:

• [Authorization: Basic xxx header] https://www.example.com/feeds/section/culture
• [Authorization: Basic xxx header] https://www.example.com/feeds/section/authors
• [Authorization: Basic xxx header] https://www.example.com/feeds/section/authors?id=500
• [Authorization: Basic xxx header] https://www.example.com/feeds/article/111-222-333

Richie’s servers won't poll section or article feeds you declare.

For both feeds, the If-None-Match mechanism will be used to avoid re-downloading and re-processing unchanged content. The ETag header of the previously fetched feed will be provided as the value of the If-None-Match header.

When fetching section feeds, Richie will calculate a hash for each article in the feed using publisher_id and article_full_version fields. If the article is new, or if the hash differs from the previously processed version, the article will be fetched and (re-)processed either immediately or when it's requested by the end user next time.

If generating your feeds is computationally intensive, we recommend uploading the feeds as static JSON files to an object store such as Amaron S3. When served from an such store, the If-None-Match negotiation and ETag generation will be handled for you automatically and no load will be placed on your application servers.

If generating static feeds is not possible, you should implement an ETag scheme that allows your application server to determine whether the caller has the latest version of the feed without needing to generate the entire section feed first.

HTTP Basic authentication as well as arbitrary query parameters may be used to authenticate access to your feed endpoints. These endpoints will not be accessed directly by end-users, but only by Richie backend services.