An API for retrieving and serving RSS feeds, with caching
Ruby
Latest commit 766a3ff Sep 18, 2015 @csm123 Update README.md
Permalink
Failed to load latest commit information.
spec rename test Sep 10, 2015
.gitignore cache to redis Aug 26, 2015
Gemfile tests Sep 10, 2015
Gemfile.lock tests Sep 10, 2015
LICENSE license Aug 25, 2015
Procfile init Aug 25, 2015
README.md Update README.md Sep 18, 2015
app.json Update app.json Sep 11, 2015
config.ru init Aug 25, 2015
rssrelay.rb from_proxy_cache is either true or false for successful requests; com… Sep 10, 2015

README.md

RSS to API

RSS to API exposes an API for retrieving RSS feeds, and includes caching to increase speed.

Key use case: Access RSS feeds from your client-side JavaScript easily and quickly.

Why this exists

Retrieving RSS feeds directly through JavaScript generally does not work due to cross-domain restrictions.

The Google Feed API provides an easy way to retrieve feeds through JavaScript, but it's officially deprecated and will likely disappear sometime soon.

There are few alternatives to the Google Feed API. The Feedly API is great, but it doesn't work directly from JavaScript and it's rate-limited like any public API.

To retrieve RSS feeds through JavaScript, then, you're forced to host your own proxy. RSS to API makes this a one-click process, through the Deploy to Heroku button below. In no time, you'll be retrieving RSS through JavaScript. You'll benefit from caching, as well, so feeds pop up quickly for your users.

Caching

RSS to API caches feeds as they're retrieved, using Redis. A Redis server is included when using the Deploy to Heroku button below.

The cache lasts for an hour by default. That is, an individual feed will be retrieved from its source only once per hour, despite the number of requests.

If a request comes in that cannot be served from cache, the app retrieves the feed and returns it.

For caching to work most effectively, include a count (i.e. how many articles to retrieve) in every request.

Usage

Retrieve the contents of an RSS feed.

Direct

https://YOUR_DOMAIN/v1/feed?url=http://www.nytimes.com/services/xml/rss/nyt/HomePage.xml&count=8&key=YOUR_KEY

JQuery

Demo

$.ajax(
  {
    url: "https://DOMAIN_FOR_THIS_APP/v1/feed?url=http://www.nytimes.com/services/xml/rss/nyt/HomePage.xml&count=8&key=YOUR_KEY"
  }
).done(
  function(data) {
    alert("Found " + data.items.length + " items");
  }
);
Parameter Description
url The URL of the RSS feed. Alternatively, you can specify a stream_id as defined in Feedly's API reference. Either the url or stream_id is required.
count The number of entries to retrieve from the feed. Default is DEFAULT_COUNT or 10. Optional.
key If you set a key with the API_KEY configuration variable, this must match that key for the request to be processed.

Results

{
  "items":
    [
      {
        "title": "Title of article", 
        "link": "Link to article",
        "published": "Date that article was published"
      },
      {
        "title": "Title of article", 
        "link": "Link to article",
        "published": "Date that article was published"
      }
    ],
  "from_proxy_cache": true /* true if from serving this feed from cache; otherwise, false */
}

Error results

{
  "error": "Invalid key"
}

Configuration variables

Only the REDIS_URL is required, and it's automatically filled if use the Deploy to Heroku button below. If you use the Deploy to Heroku button, you'll be prompted for these.

Config Variable Description
ORIGINS A comma-delimited list of domains that are allowed to submit cross-domain requests to the app. No need for commas if you're specifying just one domain. If blank, no cross-origin requests will be accepted, unless ALLOW_ALL_ORIGINS is set to true

Examples:
http://mydomain.com/,http://someotherdomain.com/
http://mydomain.com/
ALLOW_ALL_ORIGINS Set to true to allow any domain to submit cross-domain requests to this app. Not recommended.
API_KEY Set your own key that will be required to make a request to this API.
DEFAULT_COUNT The number of entries returned for a given feed by default. This can be adjusted per request. If not specified here or in the request, the default is 10.
NUMBER_OF_ITEMS_TO_CACHE_PER_FEED The number of enrties per feed to cache in Redis. If not specified, 25.
CACHE_LIFE The amount of time (in seconds) after fetching a feed to serve requests from the cache. Think about how fresh the feed needs to be for your use case vs. the speed gained from caching. If blank, 3600 or one hour - meaning that feeds will be updated from the source a maximum of once per hour.
REDIS_URL Automatically set if you deploy to Heroku below. Specifies the location of the Redis server used for caching.

Setup

Heroku (recommended)

Heroku deployment is easy and free using the button below. It includes the app itself and a Redis server.

The app will return an Internal Server Error for the first few minutes while Redis loads.

Deploy

Local

  1. Extract into a directory and run bundle
  2. Run bundle exec rackup config.ru

Toolset

  • Ruby
  • Sinatra
  • Redis