About the API doc page

[abhcs]

(I was going to post this on #1412 but noticed that there is a Discussions tab.)

I have some suggestions for improvements:

1. The output for us/calculate displayed under output format should be annotated with comments to explain the API output. For example, Google devs explain their Address Validation API with comments here.

2. The output for us/calculate has the same structure as the input: this is wasteful (due to repetition) and unintuitive for API users. A similar problem is present in the us/calculate-full API where we pass too much information to the back end with unintuitive names such as householdData.axes (The household output API calls are grossly inefficient #1230). I understand that the APIs were created from a prototyping mindset and are functional. However, since we are sharing the API with external entities, the APIs should be redesigned with good documentation for ease of use and stability. The API /us/metadata may be difficult to document because it returns too much information -- it could be broken into smaller APIs such as /us/parameters and /us/variables.

3. Move the streamlit playground (or some other form of interaction as described in Program documentation on the main website #1371) above the reference for variables and parameters. The reference for variables and parameters should be generated in the pe-<country> repos, and we can merely link to this static reference from the API doc page, rather than try to list all variables and parameters on the page itself (Too many variables and parameters are shown on the API documentation page #1413).

[anth-volk]

Thanks for this commentary, Abhishek, I think these are some solid observations. I think the first part of no. 3 is certainly actionable in the near-term, as would be no. 2, but I would imagine that's a lower-priority change. No. 2, on the other hand, is a bit more challenging considering the implications for the app, but I think there'd definitely be value in doing so.

Just as a note, this seems somewhat related to #1429.

[abhcs]

A stronger version of 1 would be the following requirement:

"Describe all APIs at a high level. For each API, describe their input and output formats annotated with comments. Use this as an example."

Now, 1 becomes harder and depends on 2.