From b1eae1724e6a1903db8866a54bf1332b143edf09 Mon Sep 17 00:00:00 2001 From: WinnyTroy Date: Fri, 21 May 2021 14:20:40 +0300 Subject: [PATCH] Expound on field query param for the data json format and geojson format --- docs/data.rst | 218 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 204 insertions(+), 14 deletions(-) diff --git a/docs/data.rst b/docs/data.rst index f72ade48d9..6b234313f5 100644 --- a/docs/data.rst +++ b/docs/data.rst @@ -242,7 +242,7 @@ Response Paginate data of a specific form -------------------------------------------- +--------------------------------- Returns a list of json submitted data for a specific form using page number and the number of items per page. Use the ``page`` parameter to specify page number and ``page_size`` parameter is used to set the custom page size. - ``page`` - Integer representing the page. @@ -287,9 +287,10 @@ Sample response with link header ] -Sort submitted data of a specific form using existing fields -------------------------------------------------------------- -Provides a sorted list of json submitted data for a specific form by specifing the order in which the query returns matching data. Use the `sort` parameter to filter the list of submissions.The sort parameter has field and value pairs. +Sort form data against a column(field) +---------------------------------------- +Returns submitted data for a specific form in a sorted order. Use the `sort` parameter to filter the list of submissions. +The sort parameter is takes a field(form column) as the key and select value pairs as demonstrated below. :: @@ -376,6 +377,58 @@ Response "subscriberid": "639027...60317" } +Fetch data on select columns for a given form +--------------------------------------------------- + +Queries select column data specified by the user. Use the ``fields`` parameter to specify the column data that should be returned. + +- ``fields`` - a comma separated list of columns on the given form. + + +.. raw:: html + + 
+  GET /api/v1/data/{form_pk}.json?fields=["field1", "field2"]
+
+ +Example +^^^^^^^^^ +:: + + curl -X GET https://api.ona.io/api/v1/data/513322.json?fields=["_id", "_last_edited"] + +Response +^^^^^^^^^ +:: + + [ + { + "_id": 64999942, + "_last_edited": null + }, + { + "_id": 64999819, + "_last_edited": null + }, + { + "_id": 64999278, + "_last_edited": null + }, + { + "_id": 64999082, + "_last_edited": null + }, + { + "_id": 60549177, + "_last_edited": null + }, + { + "_id": 60549136, + "_last_edited": null + } + ] + + Get the history of edits made to a submission ---------------------------------------------- @@ -917,18 +970,12 @@ Get a valid geojson value from the submissions - ``geo_field`` - valid field that can be converted to a geojson (Point, LineString, Polygon). - ``fields`` - additional comma separated values that are to be added to the properties section -.. raw:: html - - 
-  GET /api/v1/data/{pk}/{dataid}.geojson
-
- -**With options** +**List all the geojson values for a submission** .. raw:: html 
-  GET /api/v1/data/{pk}/{dataid}.geojson?geo_field={field_name}&fields={list,of,fields}
+  GET /api/v1/data/{form_pk}/{dataid}.geojson
Example @@ -963,12 +1010,12 @@ Response } -**List the geojson values** +**List all the geojson values for a given form** .. raw:: html 
-  GET /api/v1/data/{pk}.geojson
+  GET /api/v1/data/{form_pk}.geojson
Example @@ -1019,6 +1066,149 @@ Response }] } +**List the geojson data, for a polygon field, for a given submission** + +.. raw:: html + + 
+  GET /api/v1/data/{pk}/{dataid}.geojson?geo_field={name_of_field_on_form}
+
+ +Example +^^^^^^^^^ +:: + + curl -X GET https://api.ona.io/api/v1/data/513322/60549136.geojson?geo_field=my_geoshape + +Response +^^^^^^^^^ + + **HTTP 200 OK** + +Response +^^^^^^^^^ +:: + + { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + 36.747679, + -1.300717 + ], + [ + 36.752386, + -1.305222 + ], + [ + 36.751879, + -1.300642 + ], + [ + 36.747679, + -1.300717 + ] + ] + ] + }, + "properties": { + "id": 60549136, + "xform": 513322 + } + } + +**List the geojson data, for a geotrace field, for a given submission. Add fields to the properties attribute** + +.. raw:: html + + 
+  GET /api/v1/data/{pk}/{dataid}.geojson?geo_field={name_of_field_on_form}
+
+ +Example +^^^^^^^^^ +:: + + curl -X GET https://api.ona.io/api/v1/data/513322/60549136.geojson?geo_field=my_geotrace + +Response +^^^^^^^^^ + + **HTTP 200 OK** + +Response +^^^^^^^^^ +:: + + { + "type": "Feature", + "geometry": { + "type": "LineString", + "coordinates": [ + [ + 36.745623, + -1.302819 + ], + [ + 36.750326, + -1.299129 + ] + ] + }, + "properties": { + "id": 60549136, + "xform": 513322 + } + } + +**Fetch geojson values for a submission with populated properties attribute** + +.. raw:: html + + 
+  GET /api/v1/data/{pk}/{dataid}.geojson?fields={_id,_last_edited}
+
+ +Example +^^^^^^^^^ +:: + + curl -X GET https://api.ona.io/api/v1/data/513322/60549136.geojson?fields=_id,_last_edited + +Response +^^^^^^^^^ + + **HTTP 200 OK** + +Response +^^^^^^^^^ +:: + +{ + "type": "Feature", + "geometry": { + "type": "GeometryCollection", + "geometries": [ + { + "type": "Point", + "coordinates": [ + 36.744421, + -1.29943 + ] + } + ] + }, + "properties": { + "id": 60549136, + "xform": 513322, + "_id": 60549136, + "_last_edited": null + } +} + OSM ----