sunlightlabs/congress — pull request #451 by konklone (2014-05-15 18:28:44+00:00)
Title: Experimental RSS support

This adds experimental support for returning results in RSS format, in XML and in JSON.

RSS support has been added for 3 publicly documented endpoints: `/bills`, `/votes`, and `/upcoming_bills`, and for 2 undocumented endpoints: `/regulations` and `/documents`. I'd like to add support for `/hearings`, once we have reliable unique IDs for House and Senate hearings. (The 3 `/search` endpoints for bills, regulations and documents also support this.)

If `format=rss` is passed to one of the endpoints that supports it, the calculated results will be passed off to a set of functions in `api/rss.rb` that creates the RSS XML template, and turns each resulting object into an `
` tag. Because there is no way to tell which object is what type programmatically, this does not support the (undocumented, and should probably be killed) multi-model response feature that `/search` endpoints have.

Each model specifies which 5 fields/subfields should be mapped to `title`, `link`, `guid`, `description`, and `pubDate`. `pubDate` will always attempt to be parsed and rendered as a date. Each field can be overridden per-request by passing `rss.[field]`.

So for example, `/bills?format=rss&rss.pubDate=history.enacted_at&order=history.enacted_at` will use `history.enacted_at` as the `` field instead of the default `introduced_on` date.

If `format=rss` is passed to an endpoint that supports it, then the requested fields will be guaranteed to include the fields that will be mapped to the RSS fields (whether mapped by default or by the user through `rss.[field]` parameters).

Subfields can be specified with the `.` operator, but since I am not passing this field onto Mongo to do the subfield lookup, I needed to implement my own, naive, probably incomplete recursive depth search algorithm to translate `urls.congress` (for example) into `item['urls']['congress']`. I tested it under a variety of circumstances, but it's not going to be as good as Mongo's, and it also doesn't handle arrays at all (nor would I know how to handle them if I wanted to).

This also adds support for `format=rss-json`, which is an absurd non-format that I have proposed in a [Github ticket somewhere](https://github.com/konklone/jss/issues/10), but which I think might have legs someday. It was easy to add in, given the existing XML-based RSS format, so I did. I'm not currently planning to document that format, even experimentally.