Add more information for questionnaires on GraphQL API

Proposal

Allow API to access all attributes of a questionnaire that are currently available via the GUI.

For the GraphQL API, the following fields are available:

In the GUI, there is additional available. In the questionnaire list in Survey Setup > Questionnaires, one finds :

  • Imported date/time
  • Modified date/time
  • Created date/time
  • Mode

In the details for individual questionnaires (from Survey Setup > Questionnaires, click on a questionnaire and select Details), one also finds:

  • Imported by
  • Audio recording status (which can be gotten via the GET /api/v1/questionnaires/{id}/{version}/recordAudio endpoint)
  • Comment
  • Questionnaire preview (URL to the resource)
  • Exposed variables
  • Number of sections
  • Number of sub-sections
  • Number of rosters
  • Number of questions
  • Number of questions with conditions

My proposal is to provide all of these attributes as fields for questionnaires in the GraphQL API.

Use cases

While these use cases should not be taken as exhaustive, here are a few ideas about how I see this information being used.

For apps aimed at managing data quality, I ask users to identify the questionnaire(s) that the app should download on their behalf (e.g., all of the household questionnaires whose data to acquire and combine). Some of these attributes could help users identify the questionnaires of interest to include/exclude (e.g., import date, modified date, etc.)

In this same context, some apps ask for which variables should be used, say, to build monitoring tables (e.g, which variable captures the interview outcome). To provide the user variable choices, the app acquires the JSON file of the last imported questionnaire of interest. In the absence of any information about the questionnaire import date, the app needs to ask the user which of of the questionnaires of interest to choose as the latest. (Note: this heuristic may not always work, but it certainly would help in some contexts.)

Also, information about object counts in the questionnaire could serve as a smoke test for whether data is compatible to be combined (e.g., one has many more questions than the other, one has more sections, etc.)

Affected subsystems

To my understanding, this would only affect Headquarters.

Users

Those who use the API and build systems around the API would find this information useful.

The immediate user base, consequently, is not that large, but the the users of products built on the basis of the API is larger.

Compatibility

If new fields are added (and existing fields are unchanged), this feature would not be breaking. For those who don’t need the information, their code still works. For those who would like this information, their code could request these additional fields.