diff --git a/README.md b/README.md index 48cd931..ce5e39f 100644 --- a/README.md +++ b/README.md @@ -69,5 +69,6 @@ How these work can be found in the use task examples below. * [VRAPoten-API](VRAPoten-API.md) * [VRANbs-API](VRANbs-API.md) * [VRAHerbicide-API](VRAHerbicide-API.md) +* [VRAHaulmkilling-API](VRAHaulmkilling-API.md) diff --git a/VRAHaulmkilling.md b/VRAHaulmkilling.md new file mode 100644 index 0000000..3f1db82 --- /dev/null +++ b/VRAHaulmkilling.md @@ -0,0 +1,231 @@ +## 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 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 (to use as input for the task). +* Task 'vnd.farmmaps.task.vrahaulmkilling' 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 haulmkilling agents. +A list of haulmkilling agents can be requested by getting the "vnd.farmmaps.package.vra.haulmkilling" item and reading it's data field 'agents' array content. +> Request +```javascript +GET /api/v1/items/?it=vnd.farmmaps.package.vra.haulmkilling +``` +> Response 201 +```javascript +{ + "code": "....", + // .... + "data": + { + "agents": [ + { + "name": "spotlightplus", + "values": { + "ndvi": [ + { + "max": 0.95, + "min": 0.3, + "fexp": 1.35, + "fmul": 0.3, + "option": "risk.standard" + }, + { + "max": 0.9, + "min": 0.25, + "fexp": 1.39, + "fmul": 0.25, + "option": "risk.low" + }, + { + "max": 1, + "min": 0.35, + "fexp": 1.3, + "fmul": 0.36, + "option": "risk.high" + } + ], + "wdvi": [ + { + "max": 0.95, + "min": 0.3, + "fexp": 2.97, + "fmul": 0.3, + "option": "risk.standard" + }, + { + "max": 0.9, + "min": 0.25, + "fexp": 2.97, + "fmul": 0.25, + "option": "risk.low" + }, + { + "max": 1, + "min": 0.35, + "fexp": 2.97, + "fmul": 0.36, + "option": "risk.high" + } + ] + }, + "supportedOptions": [ + "risk.standard", + "risk.low", + "risk.high" + ] + } + ], + "validOptions": [ + "risk.standard", + "risk.low", + "risk.high", + "weed", + "split.first", + "split.second" + ] + } +} +``` + +Response 400 Itemtype not found +Response 401 Not authenticated +Response 403 No READ permissions in item +Response 404 Items not found + +The data structure contains the haulmkilling **agents** and the **valid options** available in farmmaps. +Each agent contains a list of supported options and a key value map of constants. +The key is a supported inputtype (wdvi, ndvi) and the value is a list of constant objects like so: +```javascript +{ + "name": "agentName", + "values": { + "ndvi": [ + { + "max": 0.9, + "min": 0.25, + "fexp": 2.97, + "fmul": 0.25, + "option": "risk.low" + }, + { + "max": 0.95, + "min": 0.3, + "fexp": 1.35, + "fmul": 0.3, + "option": "risk.standard" + } + ], + "wdvi": [{...}] + } +} +``` +Each constant value object has an **'option'** associated with it that should also be within the **'validOptions'** list of the data structure. + +###### Creating an application map with the VRAHaulmkilling 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. + + +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.vrahaulmkilling", + "attributes": { + "inputCode": "{itemCode}", + "inputType": "wdvi", + "agentName": "reglone", + "selectedOption": "risk.standard" + } +} +``` +> Response 201 +```javascript +{ + "code": "string", // code of task operation, can be queried for status + "taskType": "vnd.farmmaps.task.vrahaulmkilling", + "attributes": { + "inputCode": "{itemCode}", + "inputType": "wdvi", + "agentName": "reglone", + "selectedOption": "risk.standard" + } +} +``` + +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 File API. +> Request +```javascript +GET /api/v1/items/{itemcode}/data diff --git a/VRAHerbicide-API.md b/VRAHerbicide-API.md index e0b4724..f12b836 100644 --- a/VRAHerbicide-API.md +++ b/VRAHerbicide-API.md @@ -21,10 +21,11 @@ For the currently available public FarmMaps API you can take a look at swagger: * 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. + * 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) @@ -94,7 +95,7 @@ GET /api/v1/items/?it=vnd.farmmaps.package.vra.herbicide } ``` -Response 400 Tasktype not found +Response 400 Itemtype not found Response 401 Not authenticated Response 403 No READ permissions in item Response 404 Items not found @@ -169,4 +170,4 @@ Response 404 Item not found 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 +GET /api/v1/items/{itemcode}/data