niryariv/opentaba-server — pull request #54 by shevron (2014-01-01 09:26:43+00:00)
Title: Initial prototype of detailed Gushim API

Following our discussion Monday, I played around with implementing an API to get plan stats for each Gush. However, I'm not confident about both the API design and the use of Mongo's aggregation framework as I have little experience with it.

So I'd be happy for reviews and comments. This PR is meant to facilitate feedback more than I expect it to be immediately merged.

Some notes:

* The `/gushim.json` API now accepts a parameter, "detailed" so that calling `/gushim.json?detailed=true` will return an additional dictionary per Gush with the number of plans per plan status. Without parameters this API is (almost) unchanged (see next note)
* There is one small addition: I've decided to always include the `last_checked_at` field in gushim.json as it is fetched with the same query and simplifies things. This can easily be dropped but I think its useful information.
* The main reasons not to always include detailed info in `gushim.json` are:
* detailed info requires an additional, aggregate query which as I've seen is relatively heavy
* backwards compatibility of `gushim.json` (may be moot)
* bandwidth optimization, although this may be premature as I haven't really tested the size of this on real data

Some alternatives to the API would be:
* Replace `/gushim.json` to always give detailed info
* Keep the original method as is and add another method to get the detailed info: `/gushim-detailed.json`

The two queries to Mongo, as I've seen, are required unless we change our data structure or we can guarantee there are no Gushim that have no plans.