GET /api/v1/forms endpoint not returning JSON forms

michael · October 28, 2020, 11:44am

I’m calling the GET api/v1/forms endpoint. The documentation says that it “Returns a list of currently installed forms (in all available formats) in JSON format.”

From what I can tell, it is not returning JSON forms. Is that intentional?

diana · October 28, 2020, 12:54pm

I traced the code back to 2015 and the endpoint has always only returned a list of xml (enketo) forms.
I believe the reason behind this endpoint existing is integration with medic-collect, which doesn’t support SMS forms.
The list of installed SMS forms is easily visible in the settings doc.

michael · October 28, 2020, 3:29pm

Thanks. What do you think “(in all available formats)” is meant to convey? I understood it to mean enketo + JSON forms.

Perhaps we can just update the documentation for that endpoint to clearly indicate that it only includes enketo forms.

diana · October 28, 2020, 3:47pm

The endpoint accepts a header called x-openrosa-version which changes the way the response is formatted. Maybe it was about this?

github.com

medic/cht-core/blob/master/api/src/controllers/forms.js#L53


      
                resolve(xml);
              });
            });
          };
          
          
// Take view data and return simple list of forms in JSON format. The returned
          // data should be enough information to construct the request for the full
          // form. e.g. {{form_id}}.{{format}}
          //
          // @param {Object} data - couchdb view data
          const listFormsJSON = forms => {
            return JSON.stringify(forms.map(form => form.internalId + '.xml'));
          };
          
          
module.exports = {
            list: (req, res) => {
              if (!req.userCtx) {
                return serverUtils.notLoggedIn(req, res);
              }
              return formsService.getFormDocs()
                .then(forms => {

Or maybe there was general confusion into what the endpoint returned when the documentation was written?

I think it’s safe to update the documentation, unless someone has some history about this endpoint.

marc · October 28, 2020, 6:46pm

That’s right, the form list endpoint is used by (Medic) Collect to know which forms are available on the server. It uses that info to then download the individual forms to the device. Looks like we should update the documentation.

There is more up to date info on the form list API in the ODK documentation.