From 8ccef5e9f946a17b565e002d65741b50d62a25f3 Mon Sep 17 00:00:00 2001 From: Mark Date: Tue, 7 Jul 2020 20:15:27 +0000 Subject: [PATCH] Update 'VRANbs-API.md' --- VRANbs-API.md | 611 ++++++++++++++++++++++++++------------------------ 1 file changed, 316 insertions(+), 295 deletions(-) diff --git a/VRANbs-API.md b/VRANbs-API.md index 98ae5a1..8f0a4e2 100644 --- a/VRANbs-API.md +++ b/VRANbs-API.md @@ -1,295 +1,316 @@ -## VRANbs API v0.2 -[<< 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 - -**Limitations** -* Currently VRANbs only accepts input tiffs in WGS84/EPSG4326 -* Data isn't automatically deleted as farmmaps has no support for this. - * But API users can delete their own items through the farmmaps API. - -**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' needs to be 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. - * *Create 'vnd.farmmaps.itemtype.user.input' item for targetn calculation.* - * *Task 'vnd.farmmaps.task.vranbs' can be executed with the 'targetn' operation* - * *Task 'vnd.farmmaps.task.vranbs' can be executed with 'uptake' operation* to create an nitrogen uptake map. -* Task 'vnd.farmmaps.task.vranbs' must be executed with 'nitrogen' operation to create an appliance 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 VRANbs 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 vranbs 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 - -##### Using VRA Nitrogen fertilization task -The VraNbs task currently supports 3 operations: -* **targetn** - calculates the target nitrogen based on target yield. -* **uptake** - creates the nitrogen uptake map. -* **application** - creates the nitrogen fertilization application map. - -###### targetn operation -Create a 'vnd.farmmaps.itemtype.user.input' item to use in this operation. -(step not needed if you already know the target nitrogen you want to work with.) -The user.input item must parent the '{user_code}:USER_IN' item and can be obtained by calling following request: - -> Request -```javascript -GET /api/v1/Folders/my_uploads -``` -> Response 201 -```javascript -{ - "url": "/api/v1/folders/{user_code}:USER_IN", - "code": "{user_code}:USER_IN", - "name": "Uploaded", - "created": "2020-03-04T14:41:41.099557", - "updated": "2020-03-04T14:41:41.099557", - "itemType": "FOLDER", - "size": 0, - "state": 0, - "thumbnail": false -} -``` - -**Create item** -Create user.input item, pass just obtained parent code as parameter in {user_code}. -> Request -```javascript -POST /api/v1/items -{ - "parentCode": "{user_code}:USER_IN", - "itemType": "vnd.farmmaps.itemtype.user.input", - "name": "TargetN", - "dataDate": "2020-03-02T14:22:09.265Z" -} -``` - -> Response 201 Created -```javascript -{ - "parentCode": "string", - "geometry": {}, - "data": {}, - "tags": [ - "string" - ], - "url": "string", - "code": "string", - "name": "string", - "created": "2019-12-18T10:16:21.455Z", - "updated": "2019-12-18T10:16:21.455Z", - "dataDate": "2019-12-18T10:16:21.455Z", - "itemType": "string", - "sourceTask": "string", - "size": 0, - "state": 0, - "thumbnail": true -} -``` -Response 401 Not authenticated -Response 403 No WRITE permissions in parent item -Response 404 Parent Item not found - - -**Call the vranbs task** -Execute the VRANbsTask with the item code of the cropfield as parameter inside {code}. -Use the code obtained from creating the user.input item as a parameter in {itemCode}. -> Request -```javascript -POST /api/v1/items/{code}/tasks -{ - "taskType": "vnd.farmmaps.task.vranbs", - "attributes": { - "operation": "targetn", - "inputCode": "{itemCode}", - "plantingDate": "2020-02-01T00:00:00.000Z", - "measurementDate": "2020-06-01T00:00:00.000Z", - "purposeType": "consumption", // consumption, fries, potato, starch - "targetYield": "60" - } -} -``` -> Response 201 -```javascript -{ - "code": "string", - "taskType": "vnd.farmmaps.task.workflow" -} -``` - -Response 400 Tasktype not found -Response 401 Not authenticated -Response 403 No WRITE permissions in item -Response 404 Item not found - -**Query user.input targetN item** -You can query the user.input item to get the calculated targetN value from the data field of the item. -> Request -```javascript -GET /api/v1/items/{code} -``` - -> Response 200 -```javascript -{ - "parentCode": "string", - "geometry": {}, - "data": { - "TSum": "2700", - "TargetYield": "60", - "TargetN": "249.2341" - }, - "tags": [ - "string" - ], - "url": "string", - "code": "string", - "name": "TargetN", - "created": "2019-12-18T10:16:21.455Z", - "updated": "2019-12-18T10:16:21.455Z", - "dataDate": "2019-12-18T10:16:21.455Z", - "itemType": "vnd.farmmaps.itemtype.user.input", - "sourceTask": "string", - "size": 0, - "state": 0, - "thumbnail": true -} -``` - - -###### Uptake map operation -Execute the VRANbsTask 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. ex. uploaded isaria/data data. -The resulting nitrogen uptake map will be created as a child item under the cropfield item (this can be queried). -> Request -```javascript -POST /api/v1/items/{code}/tasks -{ - "taskType": "vnd.farmmaps.task.vranbs", - "attributes": { - "operation": "uptake", - "inputCode": "{itemCode}", - "plantingDate": "2020-02-01T00:00:00.000Z", - "measurementDate": "2020-06-01T00:00:00.000Z", - "inputType": "irmi", // yara, ci, irmi or wdvi - } -} -``` -> Response 201 -```javascript -{ - "code": "string", // code of task operation, can be queried for status - "taskType": "vnd.farmmaps.task.vranbs", - "attributes": { - "operation": "uptake", - "inputCode": "{itemCode}", - "inputType": "irmi", // yara, ci, irmi or wdvi - } -} -``` - -Response 400 Tasktype not found -Response 401 Not authenticated -Response 403 No WRITE permissions in item -Response 404 Item not found - -###### Application map operation -Execute the VRANbsTask 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. ex. uploaded isaria/data data. -The resulting nitrogen application map will be created as a child item under the cropfield item (this can be queried). -> Request -```javascript -POST /api/v1/items/{code}/tasks -{ - "taskType": "vnd.farmmaps.task.vranbs", - "attributes": { - "operation": "application", - "inputCode": "{itemCode}", - "plantingDate": "2020-02-01T00:00:00.000Z", - "measurementDate": "2020-06-01T00:00:00.000Z", - "inputType": "irmi", // yara, ci, irmi or wdvi - "targetN": "249.22948" - } -} -``` -> Response 201 -```javascript -{ - "code": "string", // code of task operation, can be queried for status - "taskType": "vnd.farmmaps.task.vranbs", - "attributes": { - "operation": "nitrogen", - "inputCode": "{itemCode}", - "inputType": "irmi", // yara, ci, irmi or wdvi - "targetN": "249.22948" - } -} -``` - -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 +## VRANbs API v0.3 +[<< 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 + +**Limitations** +* Currently VRANbs only accepts input tiffs in WGS84/EPSG4326 +* Data isn't automatically deleted as farmmaps has no support for this. + * But API users can delete their own items through the farmmaps API. + +**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' needs to be 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. + * *Create 'vnd.farmmaps.itemtype.user.input' item for targetn calculation.* + * *Task 'vnd.farmmaps.task.vranbs' can be executed with the 'targetn' operation* + * *Task 'vnd.farmmaps.task.vranbs' can be executed with 'uptake' operation* to create an nitrogen uptake map. +* Task 'vnd.farmmaps.task.vranbs' must be executed with 'nitrogen' operation to create an appliance 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 VRANbs 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 vranbs 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 + +##### Using VRA Nitrogen fertilization task +The VraNbs task currently supports 3 operations: +* **targetn** - calculates the target nitrogen based on target yield. +* **uptake** - creates the nitrogen uptake map. +* **application** - creates the nitrogen fertilization application map. + +###### targetn operation +Create a 'vnd.farmmaps.itemtype.user.input' item to use in this operation. +(step not needed if you already know the target nitrogen you want to work with.) +The user.input item must parent the '{user_code}:USER_IN' item and can be obtained by calling following request: + +> Request +```javascript +GET /api/v1/Folders/my_uploads +``` +> Response 201 +```javascript +{ + "url": "/api/v1/folders/{user_code}:USER_IN", + "code": "{user_code}:USER_IN", + "name": "Uploaded", + "created": "2020-03-04T14:41:41.099557", + "updated": "2020-03-04T14:41:41.099557", + "itemType": "FOLDER", + "size": 0, + "state": 0, + "thumbnail": false +} +``` + +**Create item** +Create user.input item, pass just obtained parent code as parameter in {user_code}. +> Request +```javascript +POST /api/v1/items +{ + "parentCode": "{user_code}:USER_IN", + "itemType": "vnd.farmmaps.itemtype.user.input", + "name": "TargetN", + "dataDate": "2020-03-02T14:22:09.265Z" +} +``` + +> Response 201 Created +```javascript +{ + "parentCode": "string", + "geometry": {}, + "data": {}, + "tags": [ + "string" + ], + "url": "string", + "code": "string", + "name": "string", + "created": "2019-12-18T10:16:21.455Z", + "updated": "2019-12-18T10:16:21.455Z", + "dataDate": "2019-12-18T10:16:21.455Z", + "itemType": "string", + "sourceTask": "string", + "size": 0, + "state": 0, + "thumbnail": true +} +``` +Response 401 Not authenticated +Response 403 No WRITE permissions in parent item +Response 404 Parent Item not found + + +**Call the vranbs task** +Execute the VRANbsTask with the item code of the cropfield as parameter inside {code}. +Use the code obtained from creating the user.input item as a parameter in {itemCode}. +> Request +```javascript +POST /api/v1/items/{code}/tasks +{ + "taskType": "vnd.farmmaps.task.vranbs", + "attributes": { + "operation": "targetn", + "inputCode": "{itemCode}", + "plantingDate": "2020-02-01T00:00:00.000Z", + "measurementDate": "2020-06-01T00:00:00.000Z", + "purposeType": "consumption", // consumption, fries, potato, starch + "targetYield": "60" + } +} +``` +> Response 201 +```javascript +{ + "code": "string", + "taskType": "vnd.farmmaps.task.workflow" +} +``` + +Response 400 Tasktype not found +Response 401 Not authenticated +Response 403 No WRITE permissions in item +Response 404 Item not found + +**Query user.input targetN item** +You can query the user.input item to get the calculated targetN value from the data field of the item. +> Request +```javascript +GET /api/v1/items/{code} +``` + +> Response 200 +```javascript +{ + "parentCode": "string", + "geometry": {}, + "data": { + "TSum": "2700", + "TargetYield": "60", + "TargetN": "249.2341" + }, + "tags": [ + "string" + ], + "url": "string", + "code": "string", + "name": "TargetN", + "created": "2019-12-18T10:16:21.455Z", + "updated": "2019-12-18T10:16:21.455Z", + "dataDate": "2019-12-18T10:16:21.455Z", + "itemType": "vnd.farmmaps.itemtype.user.input", + "sourceTask": "string", + "size": 0, + "state": 0, + "thumbnail": true +} +``` + + +###### Uptake map operation +Execute the VRANbsTask 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. ex. uploaded isaria/data data. +The resulting nitrogen uptake map will be created as a child item under the cropfield item (this can be queried). +> Request +```javascript +POST /api/v1/items/{code}/tasks +{ + "taskType": "vnd.farmmaps.task.vranbs", + "attributes": { + "operation": "uptake", + "inputCode": "{itemCode}", + "plantingDate": "2020-02-01T00:00:00.000Z", + "measurementDate": "2020-06-01T00:00:00.000Z", + "inputType": "irmi", // yara, ci, irmi or wdvi + } +} +``` +> Response 201 +```javascript +{ + "code": "string", // code of task operation, can be queried for status + "taskType": "vnd.farmmaps.task.vranbs", + "attributes": { + "operation": "uptake", + "inputCode": "{itemCode}", + "inputType": "irmi", // yara, ci, irmi or wdvi + } +} +``` + +Response 400 Tasktype not found +Response 401 Not authenticated +Response 403 No WRITE permissions in item +Response 404 Item not found + +###### Application map operation +Execute the VRANbsTask 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. ex. uploaded isaria/data data. +The resulting nitrogen application map will be created as a child item under the cropfield item (this can be queried). +> Request +```javascript +POST /api/v1/items/{code}/tasks +{ + "taskType": "vnd.farmmaps.task.vranbs", + "attributes": { + "operation": "application", + "inputCode": "{itemCode}", + "plantingDate": "2020-02-01T00:00:00.000Z", + "measurementDate": "2020-06-01T00:00:00.000Z", + "inputType": "irmi", // yara, ci, irmi or wdvi + "targetN": "249.22948" + } +} +``` +> Response 201 +```javascript +{ + "code": "string", // code of task operation, can be queried for status + "taskType": "vnd.farmmaps.task.vranbs", + "attributes": { + "operation": "nitrogen", + "inputCode": "{itemCode}", + "inputType": "irmi", // yara, ci, irmi or wdvi + "targetN": "249.22948" + } +} +``` + +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. +* **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 + +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", + "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