Add documentation on the fields query param on the JSON Data endpoint

[DavisRayM]

Requested Documentation Change

Currently, the documentation is a bit unclear on how the fields query works and where the query parameter is usable. It would be nice to add documentation on how the query parameter can be used and the type of responses it returns. The field is currently documented on the GeoJSON side of the endpoint but that functionality works a bit different from the JSON fields query param

Suggested changes

• Add example for the fields query param when used on the geojson format
• Add documation for the fields query param when used on the json format

[WinnyTroy]

Ive had a look at this and I believe the fields query param has been documented here

According to this documentation, the fields query param holds additional comma separated values that are to be added to the properties section.

A sample of request fetching geojson XForm data using this query param would be:

curl -X GET 'https://api.ona.io/api/v1/data/513322.geojson?fields={_last_edited}' -u 'username:password'

The response seems to iterate over all the submissions and append the value of the _last_edited field to the geojson response object's properties attribute, i.e

{"type": "FeatureCollection", "features": [{"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [36.744421, -1.29943]}]}, "properties": {"id": 60549136, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [36.744595, -1.29973]}]}, "properties": {"id": 60549177, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [-56.217314, 44.840291]}]}, "properties": {"id": 64999082, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [27.874707, 45.336702]}]}, "properties": {"id": 64999278, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [34.30051, 48.69096]}]}, "properties": {"id": 64999819, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [58.157921, 50.958427]}]}, "properties": {"id": 64999942, "xform": 513322, "_last_edited": null}}]}

A sample of request fetching geojson Submission data using this query param would be:

curl -X GET 'https://api.ona.io/api/v1/data/513322/60549136.geojson?fields={_last_edited}' -u 'username:password'

The response from this would be specific to the submission, and append the value of the _last_edited field to the geojson response object's properties attribute, i.e

{"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [36.744421, -1.29943]}]}, "properties": {"id": 60549136, "xform": 513322, "_last_edited": null}}

Further information on how to use the geo_field query param can be found here

[DavisRayM]

Ive had a look at this and I believe the fields query param has been documented here

This seems to be documented here documentation, the fields query param holds additional comma separated values that are to be added to the properties section.

A sample of request fetching geojson XForm data using this query param would be:

curl -X GET 'https://api.ona.io/api/v1/data/513322.geojson?fields={_last_edited}' -u 'username:password'

The response seems to iterate over all the submissions and append the value of the _last_edited field to the geojson response object's properties attribute, i.e

{"type": "FeatureCollection", "features": [{"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [36.744421, -1.29943]}]}, "properties": {"id": 60549136, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [36.744595, -1.29973]}]}, "properties": {"id": 60549177, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [-56.217314, 44.840291]}]}, "properties": {"id": 64999082, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [27.874707, 45.336702]}]}, "properties": {"id": 64999278, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [34.30051, 48.69096]}]}, "properties": {"id": 64999819, "xform": 513322, "_last_edited": null}}, {"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [58.157921, 50.958427]}]}, "properties": {"id": 64999942, "xform": 513322, "_last_edited": null}}]}

A sample of request fetching geojson Submission data using this query param would be:

curl -X GET 'https://api.ona.io/api/v1/data/513322/60549136.geojson?fields={_last_edited}' -u 'username:password'

The response from this would be specific to the submission, and append the value of the _last_edited field to the geojson response object's properties attribute, i.e

{"type": "Feature", "geometry": {"type": "GeometryCollection", "geometries": [{"type": "Point", "coordinates": [36.744421, -1.29943]}]}, "properties": {"id": 60549136, "xform": 513322, "_last_edited": null}}

Further information on how to use the geo_field query param can be found here

Issue with the current documentation is that it implies the fields query param can only be used when retrieving geojson data which is not the case... the query param can be used for almost all of the supported format types(Might need to test to see the full range but still)

i.e https://stage-api.ona.io/api/v1/data/.json?fields=["_id"]