From 17498e26cf55691b124d068e55afa1c10f753647 Mon Sep 17 00:00:00 2001 From: Mark Date: Wed, 10 Jun 2020 12:38:50 +0000 Subject: [PATCH] Update 'VRAHerbicide-API.md' Improved herbicide documentation with latest changes --- VRAHerbicide-API.md | 377 ++++++++++++++++++++++++-------------------- 1 file changed, 204 insertions(+), 173 deletions(-) diff --git a/VRAHerbicide-API.md b/VRAHerbicide-API.md index b7fe9cd..a6e2a5a 100644 --- a/VRAHerbicide-API.md +++ b/VRAHerbicide-API.md @@ -1,173 +1,204 @@ -## VRAHerbicide API -[<< Home](README.md) - -FarmMaps is an asynchronous architecture, the API flow keeps this in mind. -The API expects that all data is already processed and available provided, for example through the normal FarmMaps flow (frontend). - -For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html - -**Input preperation** -* Users can upload their own data if needed. (in case of when FarmMaps has not processed the required data). - * The farmmaps file API can be used for this. - -**Users can poll the task api to see if a task is completed** -**This can be achieved with the task execution id obtained from calling the 'ItemTask' API.** -[Poll task status](Polling-task-status.md) - -**Users can query the API for child items of a cropfield to see what items it has.** - -### API flow -* Authenticate User -* Optional steps - * *Create cropfield through FarmMaps API* - * Item 'vnd.farmmaps.itemtype.cropfield' must be created with its data as specified in the api. - * Task 'vnd.farmmaps.task.workflow' can be executed if needed executed to aggregate all needed data. - * This is an asynchronous process and can take a while before all data is collected in FarmMaps. - * *Upload own data* - * IF shape data, convert to geotiff. - * Querying predefined herbicide agents (for input constants if none available beforehand) -* Task 'vnd.farmmaps.task.vraherbicide' must be executed to create an application map. -* Task 'vnd.farmmaps.task.taskmap' can be executed to create a taskmap. -* Download item data (tiff of shape) - -### Steps -[Authentication](Authentication.md) - -##### Optional -[Create Cropfield](Create-Cropfield.md) -[Upload Data](Upload-Data.md) - -###### Transform shape to geotiff -The VRAHerbicide task only processes tiff items as input. -If your input data is a processed shape file it first needs to be converted to geotiff, this can be done with the 'ShapeToGeoTiffTask'. - -Pass the code of the shape item into the {code} parameter, this creates a new item with tiff data as the parent of the shape item. -This new geotiff item should be used as input to the a task. - -> Request -```javascript -POST /api/v1/items/{code}/tasks -{ - "taskType": "vnd.farmmaps.task.shapetogeotiff" -} -``` -> Response 201 -```javascript -{ - "code": "string", - "taskType": "vnd.farmmaps.task.shapetogeotiff" -} -``` - -Response 400 Tasktype not found -Response 401 Not authenticated -Response 403 No WRITE permissions in item -Response 404 Item not found - -###### Querying predefined herbicide agents. -A list of herbicide agents can be requested by finding the "vnd.farmmaps.package.vra.herbicide" items, taking the first item found and reading it's data field 'agents' array content. -> Request -```javascript -GET /api/v1/items/?it=vnd.farmmaps.package.vra.herbicide -``` -> Response 201 -```javascript -{ - "code": "....", - "data": { - "agents": [ - { - "name": "Liberator", - "SoilType": "Dalgrond", - "ExtraInputType": "Lutum", - "MinDosis": 2, - "MaxDosis": 3, - "A": 0.1428, - "B": 1.285714, - "C": 1, - "D": 97, - "E": 3, - "P": 1, - "Crop": "Zetmeelaardappelen" - } - ] - } -} -``` - -Response 400 Itemtype not found -Response 401 Not authenticated -Response 403 No READ permissions in item -Response 404 Items not found - -###### Creating an application map with the VRAHerbicide task -Execute the task with the item code of the cropfield as parameter inside {code}. -Use the input map code inside {itemCode}, specifying an inputCode for the input data item. - -{itemCode} needs the code of the data input item passed into it. -An **optional** {extraItemCode} can be passed inside the 'extraInputcode' field to process herbicide from 2 inputs. -Fill in the agent field with an agent gotten from the herbicide agents query discussed above. - -The resulting application map will be created as a child item of the cropfield item (this can be queried). -> Request -```javascript -POST /api/v1/items/{code}/tasks -{ - "taskType": "vnd.farmmaps.task.vraherbicide", - "attributes": { - "inputCode": "{itemCode}", - "extraInputCode": "{extraItemCode}", - "agent": { - "SoilType": "Dalgrond", - "ExtraInputType": "Lutum", - "MinDosis": 2, - "MaxDosis": 3, - "A": 0.1428, - "B": 1.285714, - "C": 1, - "D": 97, - "E": 3, - "P": 1, - "Crop": "Zetmeelaardappelen" - } - } -} -``` -> Response 201 -```javascript -{ - "code": "string", // code of task operation, can be queried for status - "taskType": "vnd.farmmaps.task.vraherbicide", - "attributes": { - "inputCode": "{itemCode}", - "extraInputCode": "{extraItemCode}", - "agent": { - "SoilType": "Dalgrond", - "ExtraInputType": "Lutum", - "MinDosis": 2, - "MaxDosis": 3, - "A": 0.1428, - "B": 1.285714, - "C": 1, - "D": 97, - "E": 3, - "P": 1, - "Crop": "Zetmeelaardappelen" - } - } -} -``` - -Response 400 Tasktype not found -Response 401 Not authenticated -Response 403 No WRITE permissions in item -Response 404 Item not found - -##### Create taskmap -[Create Taskmap](Create-Taskmap.md) - -##### Download the data -In case the data is available it can be downloaded with the items API. -> Request -```javascript -GET /api/v1/items/{itemcode}/download +## VRAHerbicide API +[<< Home](README.md) + +FarmMaps is an asynchronous architecture, the API flow keeps this in mind. +The API expects that all data is already processed and available provided, for example through the normal FarmMaps flow (frontend). + +For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html + +**Input preperation** +* Users can upload their own data if needed. (in case of when FarmMaps has not processed the required data). + * The farmmaps file API can be used for this. + +**Users can poll the task api to see if a task is completed** +**This can be achieved with the task execution id obtained from calling the 'ItemTask' API.** +[Poll task status](Polling-task-status.md) + +**Users can query the API for child items of a cropfield to see what items it has.** + +### API flow +* Authenticate User +* Optional steps + * *Create cropfield through FarmMaps API* + * Item 'vnd.farmmaps.itemtype.cropfield' must be created with its data as specified in the api. + * Task 'vnd.farmmaps.task.workflow' can be executed if needed executed to aggregate all needed data. + * This is an asynchronous process and can take a while before all data is collected in FarmMaps. + * *Upload own data* + * IF shape data, convert to geotiff. + * Querying predefined herbicide agents (for input constants if none available beforehand) +* Task 'vnd.farmmaps.task.vraherbicide' must be executed to create an application map. +* Task 'vnd.farmmaps.task.taskmap' can be executed to create a taskmap. +* Download item data (tiff of shape) + +### Steps +[Authentication](Authentication.md) + +##### Optional +[Create Cropfield](Create-Cropfield.md) +[Upload Data](Upload-Data.md) + +###### Transform shape to geotiff +The VRAHerbicide task only processes tiff items as input. +If your input data is a processed shape file it first needs to be converted to geotiff, this can be done with the 'ShapeToGeoTiffTask'. + +Pass the code of the shape item into the {code} parameter, this creates a new item with tiff data as the parent of the shape item. +This new geotiff item should be used as input to the a task. + +> Request +```javascript +POST /api/v1/items/{code}/tasks +{ + "taskType": "vnd.farmmaps.task.shapetogeotiff" +} +``` +> Response 201 +```javascript +{ + "code": "string", + "taskType": "vnd.farmmaps.task.shapetogeotiff" +} +``` + +Response 400 Tasktype not found +Response 401 Not authenticated +Response 403 No WRITE permissions in item +Response 404 Item not found + +###### Querying predefined herbicide agents. +A list of herbicide agents can be requested by finding the "vnd.farmmaps.package.vra.herbicide" items, taking the first item found and reading it's data field 'agents' array content. +> Request +```javascript +GET /api/v1/items/?it=vnd.farmmaps.package.vra.herbicide +``` +> Response 201 +```javascript +{ + "code": "....", + "data": { + "agents": [ + { + "name": "Liberator", + "SoilType": "Dalgrond", + "ExtraInputType": "Lutum", + "MinDosis": 2, + "MaxDosis": 3, + "A": 0.1428, + "B": 1.285714, + "C": 1, + "D": 97, + "E": 3, + "P": 1, + "Crop": "Zetmeelaardappelen" + } + ] + } +} +``` + +Response 400 Itemtype not found +Response 401 Not authenticated +Response 403 No READ permissions in item +Response 404 Items not found + +###### Creating an application map with the VRAHerbicide task +Execute the task with the item code of the cropfield as parameter inside {code}. +Use the input map code inside {itemCode}, specifying an inputCode for the input data item. + +{itemCode} needs the code of the data input item passed into it. +An **optional** {extraItemCode} can be passed inside the 'extraInputcode' field to process herbicide from 2 inputs. +Fill in the agent field with an agent gotten from the herbicide agents query discussed above. + +The resulting application map will be created as a child item of the cropfield item (this can be queried). +> Request +```javascript +POST /api/v1/items/{code}/tasks +{ + "taskType": "vnd.farmmaps.task.vraherbicide", + "attributes": { + "inputCode": "{itemCode}", + "extraInputCode": "{extraItemCode}", + "agent": { + "SoilType": "Dalgrond", + "ExtraInputType": "Lutum", + "MinDosis": 2, + "MaxDosis": 3, + "A": 0.1428, + "B": 1.285714, + "C": 1, + "D": 97, + "E": 3, + "P": 1, + "Crop": "Zetmeelaardappelen" + } + } +} +``` +> Response 201 +```javascript +{ + "code": "string", // code of task operation, can be queried for status + "taskType": "vnd.farmmaps.task.vraherbicide", + "attributes": { + "inputCode": "{itemCode}", + "extraInputCode": "{extraItemCode}", + "agent": { + "SoilType": "Dalgrond", + "ExtraInputType": "Lutum", + "MinDosis": 2, + "MaxDosis": 3, + "A": 0.1428, + "B": 1.285714, + "C": 1, + "D": 97, + "E": 3, + "P": 1, + "Crop": "Zetmeelaardappelen" + } + } +} +``` + +Response 400 Tasktype not found +Response 401 Not authenticated +Response 403 No WRITE permissions in item +Response 404 Item not found + +##### Optional input parameters ##### +There are some optional task attribute input parameters for greater flexibility. + +* **inputLayerName** +Allows you to specify which layer to use for an input item. +* **extraInputLayerName** +Allows you to specify which layer to use for the extra input item. +* **minPercentile** value between 0.0 - 1.0 +Allows you to specify the minimum percentile value to 'filter' lower bound input data +* **maxPercentile** value between 0.0 - 1.0 +Allows you to specify the maximum percentile value to 'filter' upperbound bound input data +* **plantingDate** if relevant +Allows you to specify the date the crop is planted. +* **measurementDate** if relevant +allows you to specify the date when the measurements were taken. + +Default input layer name for herbicide is the agent inputType used (lutum, om). +Default percentile values for herbicide are 0.0 and 1.0. +Default dates are 'inherited' from the cropfield item passed to the task. + +```javascript +{ + "inputLayerName": "customLayerName", + "extraInputLayerName": "customLayerName", + "plantingDate": "2020-02-01T00:00:00.000Z", + "measurementDate": "2020-06-01T00:00:00.000Z", + "minPercentile": "0.1", + "maxPercentile": "0.95" +} +``` + +##### Create taskmap +[Create Taskmap](Create-Taskmap.md) + +##### Download the data +In case the data is available it can be downloaded with the items API. +> Request +```javascript +GET /api/v1/items/{itemcode}/download