From 8337df7c63541c33d0fea8c8b766f9c0ccb90552 Mon Sep 17 00:00:00 2001 From: Mark van der Wal Date: Thu, 25 Feb 2021 10:44:36 +0000 Subject: [PATCH] Update 'VRAPoten-API.md' --- VRAPoten-API.md | 182 ++++++++++++++++++++++++++---------------------- 1 file changed, 98 insertions(+), 84 deletions(-) diff --git a/VRAPoten-API.md b/VRAPoten-API.md index 9508a5a..622f06e 100644 --- a/VRAPoten-API.md +++ b/VRAPoten-API.md @@ -1,84 +1,98 @@ -## VRAPoten API v0.1.1 -[<< Home](README.md) - -FarmMaps is an asynchronous architecture, the API flow keeps this in mind. -The API 2 that all data is already processed and available provided, for example through the normal FarmMaps flow. - -For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html - -**Input preperation** -* VRAPoten requires specific input which needs to be provided by the FarmMaps API or user interface. - * You can activate the VRAPotenTask with the Task API, passing the just created cropfield item code as a parameter. -* Users can upload their own soilmaps if needed. (in case of when FarmMaps has not processed the required data). - * The 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) - -### API flow -* Authenticate User -* *Create cropfield through FarmMaps API (optioneel)* - * Item 'FOLDER' must be created for parent to cropfields. - * 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 (optioneel) -* Task 'vnd.farmmaps.task.vrapoten' must be executed to create an appliance map. -* Task 'vnd.farmmaps.task.taskmap' must be executed to create a taskmap. -* Download item data (tiff of shape) - -### Steps -###### Authentication -[Authentication](Authentication.md) - -###### Create cropfield with FarmMaps API (optional) -[Create Cropfield](Create-Cropfield.md) - -###### Uploading own data (optional) -[Upload Data](Upload-Data.md) - -###### Creating appliance maps -Execute the VRAPotenTask with the item code of the cropfield as parameter inside {code}. -Use the input map code inside {itemCode}, specifying an inputCode is optional. -In case of no specified inputCode the BOFEK data is looked up and if it could not be found the task gives an error. - -> Request -```javascript -POST /api/v1/items/{code}/tasks -{ - "taskType": "vnd.farmmaps.task.vrapoten", - "attributes": { - "inputCode": "{itemCode}", - "meanDensity": "30", - "variation": "20" - } -} -``` -> Response 201 -```javascript -{ - "code": "string", - "taskType": "vnd.farmmaps.task.workflow", - "delay": "", - "attributes": { - "additionalProp1": "string", - "additionalProp2": "string", - "additionalProp3": "string" - } -} -``` - -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 +## VRAPoten API v0.1.1 +[<< Home](README.md) + +FarmMaps is an asynchronous architecture, the API flow keeps this in mind. +The API 2 that all data is already processed and available provided, for example through the normal FarmMaps flow. + +For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html + +**Input preperation** +* VRAPoten requires specific input which needs to be provided by the FarmMaps API or user interface. + * You can activate the VRAPotenTask with the Task API, passing the just created cropfield item code as a parameter. +* Users can upload their own soilmaps if needed. (in case of when FarmMaps has not processed the required data). + * The 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) + +### API flow +* Authenticate User +* *Create cropfield through FarmMaps API (optioneel)* + * Item 'FOLDER' must be created for parent to cropfields. + * 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 (optioneel) +* Task 'vnd.farmmaps.task.vrapoten' must be executed to create an appliance map. +* Task 'vnd.farmmaps.task.taskmap' must be executed to create a taskmap. +* Download item data (tiff of shape) + +### Steps +###### Authentication +[Authentication](Authentication.md) + +###### Create cropfield with FarmMaps API (optional) +[Create Cropfield](Create-Cropfield.md) + +###### Uploading own data (optional) +[Upload Data](Upload-Data.md) + +###### Creating appliance maps +Execute the VRAPotenTask with the item code of the cropfield as parameter inside {code}. +Use the input map code inside {itemCode}, specifying an inputCode is optional. +In case of no specified inputCode the BOFEK data is looked up and if it could not be found the task gives an error. + +> Request +```javascript +POST /api/v1/items/{code}/tasks +{ + "taskType": "vnd.farmmaps.task.vrapoten", + "attributes": { + "inputCode": "{itemCode}", + "meanDensity": "30", + "variation": "20" + } +} +``` +> Response 201 +```javascript +{ + "code": "string", + "taskType": "vnd.farmmaps.task.workflow", + "delay": "", + "attributes": { + "additionalProp1": "string", + "additionalProp2": "string", + "additionalProp3": "string" + } +} +``` + +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. + +* **countPerArea** +Allows you to specify if spacing in cm needs to be calculated to count per area in m2. + +default is false + +```javascript +{ + "countPerArea": true, +} + +###### 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