Requirements: Data Fetching for the Comparison Tool

The Compare tool needs a data fetch layer to retrieve and prepare data from the API for plotting. What follows is a high-level spec for those requirements.

Data streams: generally speaking

All data streams, whether for totals or breakdowns, should follow a common format. Roughly:

• at the top level, it should be an array. Each item in the array should be a year of data.
  • This array should always be sorted in reverse chronological order.
  • For same-year comparisons, secondary sort by type: [adjusted, adopted, proposed]
• for each year:
  • key metadata includes the fiscal year, the budget type, the account type (spending vs revenue), and the breakdown (total, department, category)
  • data should be an array of {key, value} objects or something similar. Values should be typecast to numbers

Totals

The totals endpoint provides totals for all available budgets, including all budget types (proposed, adopted, adjusted). We can use this for two purposes:

1. to populate a list of all available budgets for selecting budgets to compare
   • output should be something like a list, e.g. [{year: '14-15', type: 'adopted'}, {year: '14-15', type: 'proposed'}, ...], that the UI can use to populate selection widgets with valid options.
2. once budgets are selected, populating the "totals" comparison with data immediately, without requiring an additional API request.

Breakdowns

There are four main breakdown endpoints we plan to use: Spending by Dept, Spending by Category, Revenue by Dept, Revenue by Category. For all of these, the same basic pattern holds:

1. Request breakdown data for selected years. (Endpoints return one year at a time, so multiple requests are required.)
2. When all requests return successfully, the UI will render plots.

We need to be able to query each endpoint independently because the UI may dynamically expose only one or two breakdowns at a time and we would like to avoid unnecessary network requests by querying the data on demand.