It would be useful to have more Examples of API requests

[mbanders]

Looking at https://github.com/RTICWDT/open-data-maker/blob/master/API.md

It would be really useful to have more example API requests, the top searches I think people would do:

• For a single university, I want a table of all majors and their salaries.
• For a single major, I want a table of all the schools (or top N schools) and salary & debt.

[btskinner]

I would appreciate some more examples as well. Right now, it's not clear to me how the API handles requests for data elements from both institution and field of study data sources.

For example, it seems that a user can request elements from both sources in a single call. When this occurs, is it correct that:

1. The data elements from the fieldsOfStudy_data files will be nested within elements from the institutution_data files? For example, the school name is in both locations: this means that an API call for both id (sans root) and programs.cip_4_digit.id will return the name at two levels --- overall and repeated for each program --- correct?

2. Institution and field of study data are linked by year as defined in the data dictionary? For example, if the user requests elements from 2016, then institution elements come from MERGED2016_2017_PP. and field of study elements come from ProgramData1516_1617 --- correct?

3. If (2) is correct, how is latest determined? Is it the latest in whichever both data locations have values or does one location take precedence?

4. If a data element doesn't exist in one of the data locations (say the user asked for 2017 elements, which aren't available in the field of study data), the API simply fails?

Apologies for the list of questions --- just trying to be clear. Thanks as always.