From bbad6f20679434df323a4d645aed3066f153e911 Mon Sep 17 00:00:00 2001 From: Mark van der Wal Date: Wed, 11 Mar 2020 09:04:28 +0000 Subject: [PATCH] Update page 'VRANbs API' --- VRANbs-API.md | 286 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 286 insertions(+) create mode 100644 VRANbs-API.md diff --git a/VRANbs-API.md b/VRANbs-API.md new file mode 100644 index 0000000..4989c81 --- /dev/null +++ b/VRANbs-API.md @@ -0,0 +1,286 @@ +## VRANbs API v0.1 +[<< Home](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Home) + +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 soilmaps 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.** +**Users can query the API for child items of a cropfield to see what data 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 soil data* + * *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](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Authentication) + +##### Optional +[Create Cropfield](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Create-Cropfield) +[Upload Data](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Upload-Data) + +###### 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 uptake map. +* **nitrogen** - creates the fertilization appliance 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** +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}", + "inputType": "irmi", // yara, ci, irmi or wdvi + "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 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}", + "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 + +###### Nitrogen 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 appliance 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": "nitrogen", + "inputCode": "{itemCode}", + "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](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Create-Taskmap) + +##### Download the data +In case the data is available it can be downloaded with the File API. +> Request +```javascript +GET /api/v1/items/{itemcode}/data \ No newline at end of file